diff --git a/.gitignore b/.gitignore index 444349a..6484181 100644 --- a/.gitignore +++ b/.gitignore @@ -41,3 +41,9 @@ Thumbs.db # git add -A picks an existing one up as an embedded repository, which leaves a # gitlink to a directory nobody else has. .claude/ + +# A second world, used to count the empty section share of a generated overworld +# (EmptySectionCensusTest, -Pfalco.census.world). falco-demo/world carries its own +# .gitignore because that directory is part of the module; this one is not, and a +# world is large, often private, and never belongs in a git repository. +falco-demo/full-world/ diff --git a/README.md b/README.md index 7fa05e3..2ec5ae2 100644 --- a/README.md +++ b/README.md @@ -97,6 +97,14 @@ The listener is the explicit route: you decide which chunks are lit and when. Th that needs no listener at all — `instance.setChunkSupplier(scheduler.supplier())`, covered in [Light Engine](https://github.com/OneLiteFeatherNET/Falco/wiki/Light-Engine). +**That shorter route needs `falco-instance` on the classpath as well**, and the two lines above are +not enough for it. The chunks the supplier produces are `FalcoChunk`s — which is what lets one chunk +carry Falco's light *and* Falco's lifecycle instead of forcing a choice between them — and +`falco-instance` is `compileOnly` in `falco-light`, so it does not arrive with the artefact. Add +`implementation("net.onelitefeather:falco-instance:")` next to the two above before calling +`supplier()`; everything else in `falco-light`, including the `lighting.calculate` route used here, +works without it. + ### 3. Put a world where the loader looks `worlds/lobby/` is the **world root** — the directory that contains `region/`, or diff --git a/build.gradle.kts b/build.gradle.kts index e4be11e..b70c978 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -111,6 +111,14 @@ project(":falco-bom") { val apiBaselineVersion: String = providers.gradleProperty("apiBaselineVersion").get() +val apiBreaksFile: File = rootProject.file("gradle/api-breaks.properties") + +val apiBreaks: Map = if (!apiBreaksFile.exists()) emptyMap() else + java.util.Properties() + .apply { apiBreaksFile.inputStream().use { load(it) } } + .entries + .associate { it.key.toString() to it.value.toString().trim() } + configure(publishedModules - project(":falco-bom")) { apply(plugin = "me.champeau.gradle.japicmp") @@ -120,16 +128,32 @@ configure(publishedModules - project(":falco-bom")) { isTransitive = false } + val declaredBreaks: List = apiBreaks["${project.name}.classExcludes"] + ?.split(",") + ?.map(String::trim) + ?.filter(String::isNotEmpty) + .orEmpty() + val checkApiCompatibility = tasks.register("checkApiCompatibility") { oldClasspath.from(apiBaseline) newClasspath.from(tasks.named("jar").flatMap { it.archiveFile }) onlyBinaryIncompatibleModified.set(true) failOnModification.set(true) ignoreMissingClasses.set(true) + classExcludes.set(declaredBreaks) htmlOutputFile.set(layout.buildDirectory.file("reports/japicmp/${project.name}.html")) txtOutputFile.set(layout.buildDirectory.file("reports/japicmp/${project.name}.txt")) doFirst { + if (apiBreaks.keys.any { it.endsWith(".classExcludes") }) { + require(apiBreaks["baseline"] == apiBaselineVersion) { + "${apiBreaksFile.name} declares accepted API breaks against baseline " + + "${apiBreaks["baseline"]}, but apiBaselineVersion is $apiBaselineVersion. " + + "Every exception in that file was judged against the older baseline and " + + "excludes its type from the check entirely, so each one has to be " + + "re-examined and either deleted or re-justified before the version moves." + } + } val resolved = apiBaseline.resolve() require(resolved.isNotEmpty()) { "the API baseline net.onelitefeather:${project.name}:$apiBaselineVersion resolved to nothing" diff --git a/docs/benchmarks/README.md b/docs/benchmarks/README.md new file mode 100644 index 0000000..fc5f783 --- /dev/null +++ b/docs/benchmarks/README.md @@ -0,0 +1,164 @@ +# Benchmark baselines + +This directory holds the JMH result files every published figure of this project is drawn from, and +the record of the machine each of them was taken on. It is the durable half of `falco-benchmarks`: +the benchmark sources say what is measured and why, these files say what came out. + +## Why the results do not live in `build/` + +The `jmh` block of `falco-benchmarks/build.gradle.kts` writes to +`build/reports/jmh/results.json` by default, and `./gradlew clean` deletes it. A baseline that a +routine clean removes is not a baseline — the next run has nothing to be compared against, and the +figure in the README turns back into a claim. Result files therefore land here, under version +control, next to the conditions that produced them. + +Two Gradle properties make the Gradle path write here as well, so a run started with +`./gradlew :falco-benchmarks:jmh` does not have to be repeated through the jar to be kept: + +``` +./gradlew :falco-benchmarks:jmh \ + -Pjmh.include=SectionAllocationBenchmark \ + -Pjmh.forks=3 \ + -Pjmh.resultsFile=docs/benchmarks/baseline-2026-08-01/SectionAllocationBenchmark.json \ + -Pjmh.humanFile=docs/benchmarks/baseline-2026-08-01/SectionAllocationBenchmark.human.txt +``` + +Both paths are resolved against the repository root, and an absolute path is taken as it is. +`-Pjmh.forks` exists alongside them because the classes carry `@Fork(1)` and the Gradle path would +otherwise silently produce a single-fork result while the script produces a three-fork one. It is +applied after `-Pjmh.quick`, so passing both leaves the fork count where `-Pjmh.forks` puts it. + +## Layout + +``` +docs/benchmarks/ + full-run.sh the script that produces a baseline + baseline-/ + conditions.txt machine, JVM, commit, configuration, idle answer + .json JMH result, one file per class + .human.txt the printed transcript of the same run + SetBlockContentionBenchmark-t.json one file per thread count +``` + +**One file per benchmark class, never one shared file.** JMH rewrites `-rff` completely on every +invocation rather than appending to it, so a second run into the same path destroys the first. That +is not a hypothetical: the scouting run of 2026-08-01 pointed six invocations at the single +`build/reports/jmh/results-quick.json` the build configures, and only the last of the six survived +in it. The same applies to the thread sweep of `SetBlockContentionBenchmark`, where five processes +run in a row and the fifth would otherwise be the only one left. + +## Running a baseline + +``` +docs/benchmarks/full-run.sh --dry-run # print every command and the time estimate +docs/benchmarks/full-run.sh # about 2 h 35 min +``` + +The script derives its estimate per benchmark class and prints the derivation in its header. Read +it before starting: this is a run measured in hours, not minutes, and it needs the machine to +itself for all of them. It refuses to start above a one minute load average of 1.5 for that reason. +A Gradle build, an IDE indexing pass or a second agent compiling in the same checkout is enough to +change the numbers, and none of it is visible afterwards in the result file. + +The script builds the benchmark jar once with Gradle and then runs each measurement as a plain +`java -jar`. That is deliberate. Driving the measurements through `./gradlew :falco-benchmarks:jmh` +keeps a Gradle daemon alive next to every forked measurement JVM, competing for the same cores; the +jar path leaves exactly one JVM running while a benchmark is being measured. + +## Comparing a later run against a baseline + +Point the new run at a new file, never at the old one: + +``` +./gradlew :falco-benchmarks:jmhJar +java -jar falco-benchmarks/build/libs/falco-benchmarks-*-jmh.jar \ + 'ChunkComparisonBenchmark' -e '\.(minestomCopy|falcoCopy)$' \ + -f 3 -wi 5 -i 5 -prof gc -foe true \ + -rf json -rff /tmp/chunk-comparison-candidate.json +``` + +Then read the two files side by side — [JMH Visualizer](https://jmh.morethan.io/) takes several at +once — and read `conditions.txt` first. A comparison across two machines, two JVM builds or two +governor settings is not a comparison. Nothing in the JSON warns about it; the conditions file is +the only place that information exists. + +## What is in a baseline and what is not + +The run covers six benchmark classes at three forks, five warmup and five measurement iterations of +one second, with `-prof gc`. One thing is deliberately kept out of it, and one thing is deliberately +filed under a name that says it may not be quoted. + +**`ChunkComparisonBenchmark.minestomCopy` and `.falcoCopy` are not part of the baseline.** They are +documented in their own javadoc as non-comparable: constructing a chunk for an `InstanceContainer` +leaves an entry in a viewer cache that nothing removes and that no later key ever matches, so +`minestomCopy` reports a copy plus a hash map that grows for the length of the trial. +`ChunkViewerCacheLeakTest` establishes the mechanism. The comparable pair is +`minestomCopyIsolated` against `falcoCopyIsolated`, and it is in the baseline. + +The scouting run shows why the two arms cannot be a baseline even taken on their own terms. Their +per iteration values rise during the measurement — at `distinctStates = 64` the three iterations of +the `minestomCopy` fork read 296, 313 and 364 µs/op, and at 1024 they read 282, 304 and 390 µs/op, +a rise of 23 % and 38 % — while every control arm on the same fork is flat to within 2 % +(`falcoSetBlock` at 1024: 106.86, 107.19, 106.64). A quantity that grows while it is being measured +does not have a value; it has a slope, and the mean printed for it is a function of how long the +iteration ran. Changing `-i` changes the answer. + +Their allocation column, in contrast, is exact and is worth having: `minestomCopy` minus +`falcoCopy` in `gc.alloc.rate.norm` was 257.1, 257.3 and 257.3 B/op at `distinctStates` 1, 64 and +1024 — constant across the axis, at an error below 0.6 B. That is the per copy cost of the leak, it +is the same whatever the chunk holds, and it is the number worth publishing about this pair. + +The two arms are therefore run, once, under `--with-leak-arms`, into a file named +`ChunkComparisonBenchmark-viewer-cache-leak-NOT-A-BASELINE.json`. The name is the warning, because +the file will outlive the conversation that produced it. + +## What has to be recorded next to a number + +`conditions.txt` is written by the script and answers every field +[the performance report form](../../.github/ISSUE_TEMPLATE/performance-report.yml) asks reporters +for: CPU model and core count, the JMH thread count, the JVM vendor and version, the operating +system, the Falco commit, the exact configuration, and whether the machine was idle. The last one +is the only field the script cannot fill in, and it is left as an open question at the end of the +file. Answer it before quoting anything from the run. The figures currently on the wiki's Project +Status page were taken on a machine that was not idle and say so, which is the only reason they are +still usable. + +## The tests of this module do not run on macOS + +`:falco-benchmarks:test` is skipped on macOS and only there. Everything else in the repository runs +on all three runners as before; this module is the exception, and Gradle prints the reason next to +the `SKIPPED` marker rather than passing over it silently. + +**What was observed.** On 2026-08-03 the macOS job of both open pull requests stopped in +`:falco-benchmarks:test` and never came back. The other five modules — instance, light, anvil, demo, +archunit — completed and wrote all 85 result files; this module wrote +`in-progress-results-generic.bin` and `output-events.bin` at zero bytes, meaning the test JVM had +been started and no test had reported anything at all. The job was silent for 31 minutes before it +was cancelled, and the runner then terminated four orphan `java` processes. The same commit builds +in 3m30s on ubuntu and 5m10s on windows, and the same macOS runner builds `main` green in 2m1s, so +neither the runner nor the workflow is what differs. + +**Why this module and no other.** It is the only one whose test JVM is started with +`-Djdk.attach.allowAttachSelf=true`, `-XX:+EnableDynamicAgentLoading`, `-Djol.magicFieldOffset=true` +and an explicit `UseCompactObjectHeaders` setting, and with a 4 GB heap on a runner that has 7 GB. +Those exist because jol measures retained size by attaching to its own VM. Which of them is the one +that hangs on arm64 has not been established — the module is excluded, the cause is not diagnosed, +and this paragraph says so rather than implying otherwise. + +**What is given up.** These are the tests that carry the central claim of the storage work: +`ChunkFootprintTest` measures the 25 objects and 840 bytes of a fresh chunk, `PaletteFootprintTest` +the palette break-even, `FalcoChunkEquivalenceTest` the behavioural equality against Minestom. They +keep running on ubuntu and windows in every pull request, so the claim stays covered on two of three +platforms — but a regression that only shows on arm64 would now pass unnoticed. The figures were +never platform independent to begin with: retained size depends on the object header layout, which +is what `UseCompactObjectHeaders` switches, so a number taken on arm64 was never interchangeable +with the published one. + +**To run them on macOS anyway**, for instance to work on the hang: + +```bash +./gradlew :falco-benchmarks:test -Pfalco.macOsFootprintTests +``` + +The property forces the task on regardless of the operating system. Expect it to hang until the +cause is found. diff --git a/docs/benchmarks/full-run.sh b/docs/benchmarks/full-run.sh new file mode 100755 index 0000000..233c9ae --- /dev/null +++ b/docs/benchmarks/full-run.sh @@ -0,0 +1,315 @@ +#!/usr/bin/env bash +# +# Falco JMH baseline run. +# +# Produces the citable baseline numbers of this project: one JSON result file and one human +# readable transcript per benchmark class, under docs/benchmarks/baseline-/, next to a +# conditions.txt that records the machine the numbers were taken on. Nothing this script writes +# lands in build/, because a clean deletes build/ and a baseline that a clean deletes is not a +# baseline. +# +# Usage: +# docs/benchmarks/full-run.sh --dry-run print every command and the time estimate +# docs/benchmarks/full-run.sh run the citable baseline (~2 h 35 min) +# docs/benchmarks/full-run.sh --with-leak-arms additionally run the two non-comparable copy +# arms into their own, separately named file +# docs/benchmarks/full-run.sh --date 2026-08-02 override the directory date stamp +# docs/benchmarks/full-run.sh --forks 5 override the fork count (default 3) +# docs/benchmarks/full-run.sh --force run even though the machine is not idle +# +# Read docs/benchmarks/README.md before running this. In particular: the run takes over two hours, +# it must have the machine to itself, and a second Gradle build started while it runs invalidates +# every number it has produced up to that point. + +set -euo pipefail + +# --------------------------------------------------------------------------------------------- +# Configuration +# --------------------------------------------------------------------------------------------- + +REPO_ROOT="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/../.." && pwd)" + +# Three forks, not one. Five of the six benchmark classes carry @Fork(1), which measures a single +# JVM launch: the +- JMH then prints covers variance between iterations of that one launch and says +# nothing about variance between launches. The README of this repository documents a case where +# that mattered — a two-thread RegionFileComparisonBenchmark row that did not reproduce on an +# independent run of the identical configuration, moving from a usable interval to a half width 8,3 +# times its own mean. One fork cannot see that; it is invisible by construction. +# +# Three is the smallest count that can show a fork disagreeing with the others. At two forks a +# disagreement is a tie with no majority and no way to tell which launch was the odd one; at three +# there is a middle value, and JMH keeps the per fork raw data in the JSON so the disagreement can +# be read afterwards rather than guessed at. Five would be better and costs 1,67 times as long +# (about 4 h 20 min instead of 2 h 35 min) — pass --forks 5 for the individual claims that end up +# quoted in the README, and record which of the two configurations produced which table. +FORKS="${FORKS:-3}" + +# Restated on the command line although the annotations already say 5 and 5. The issue template +# asks reporters for "the full invocation, including every JMH flag", and a command line that omits +# what the annotations supply is only complete for someone holding the matching source revision. +WARMUP_ITERATIONS=5 +MEASUREMENT_ITERATIONS=5 + +# The thread counts of the contention sweep. @Threads is not an axis JMH can cross with @Param, so +# each of these is a separate process and a separate result file. +CONTENTION_THREADS=(1 2 4 8 16) + +# Above this one minute load average the script refuses to start. A measurement taken next to +# somebody else's compile measures that compile. The scouting run this baseline replaces was taken +# on a machine that was not idle, and said so. +MAX_LOAD=1.5 + +DRY_RUN=0 +WITH_LEAK_ARMS=0 +FORCE=0 +DATE_STAMP="$(date -u +%Y-%m-%d)" + +while [[ $# -gt 0 ]]; do + case "$1" in + --dry-run) DRY_RUN=1; shift ;; + --with-leak-arms) WITH_LEAK_ARMS=1; shift ;; + --force) FORCE=1; shift ;; + --date) DATE_STAMP="$2"; shift 2 ;; + --forks) FORKS="$2"; shift 2 ;; + -h|--help) sed -n '2,25p' "${BASH_SOURCE[0]}"; exit 0 ;; + *) echo "unknown argument: $1" >&2; exit 2 ;; + esac +done + +OUT_DIR="$REPO_ROOT/docs/benchmarks/baseline-$DATE_STAMP" + +# --------------------------------------------------------------------------------------------- +# The plan, and what it costs +# --------------------------------------------------------------------------------------------- +# +# Every figure below is derived, not guessed. The scouting run of 2026-08-01 gives the two +# constants the derivation needs, per benchmark class: +# +# combinations x forks x (warmup + measurement) x iteration time + combinations x forks x start +# +# The scouting run measured 118 combinations at -f 1 -wi 2 -i 3, so 5 s of iterations per +# combination, and its six invocations took 32 s, 44 s, 151 s, 245 s, 190 s and 65 s of wall clock, +# 727 s in total. Subtracting the iteration time from the wall clock and dividing by the number of +# forks gives the per fork start cost of each class, which is the only part that is not arithmetic: +# +# SectionAllocationBenchmark 5 combos, 25 s iterations, 32 s wall -> 1,4 s per fork +# SetBlockContentionBenchmark 6 combos, 30 s iterations, 44 s wall -> 2,3 s per fork +# ChunkComparisonBenchmark 24 combos, 120 s iterations, 151 s wall -> 1,3 s per fork +# LazySectionBenchmark 39 combos, 195 s iterations, 245 s wall -> 1,3 s per fork +# PaletteIndirectGetBenchmark 36 combos, 180 s iterations, 190 s wall -> 0,3 s per fork +# ChunkResendCostBenchmark 8 combos, 40 s iterations, 65 s wall -> 3,1 s per fork +# +# The three classes that call MinecraftServer.init() cost between 1,3 s and 3,1 s per fork, not the +# minutes their javadoc assumes when it argues for a single fork. At the full configuration a fork +# runs 10 s of iterations, so the start is between 12 % and 31 % of it — which is what makes three +# forks affordable at all. +# +# At -f 3 -wi 5 -i 5 each combination therefore costs 3 x 10 s of iterations plus 3 x the start: +# +# # Benchmark Combinations Estimate +# - -------------------------------------------- ----------------------- ----------- +# 1 SectionAllocationBenchmark 5 methods x 1 = 5 2 min 51 s +# 2 SetBlockContentionBenchmark, t = 1,2,4,8,16 2 x 3 x 5 runs = 30 18 min 27 s +# 3 ChunkResendCostBenchmark 4 methods x 4 = 16 10 min 29 s +# 4 PaletteIndirectGetBenchmark 6 methods x 6 = 36 18 min 30 s +# 5 LazySectionBenchmark 13 methods x 3 = 39 21 min 60 s +# 6 ChunkComparisonBenchmark, comparable arms 8 methods x 18 = 144 81 min 24 s +# - -------------------------------------------- ----------------------- ----------- +# Citable baseline 270 2 h 34 min +# Optional: ChunkComparisonBenchmark leak arms 2 methods x 18 = 36 20 min 20 s +# Optional: contention monitor evidence, JFR 1 combination = 1 < 1 min +# -------------------------------------------- ----------------------- ----------- +# Everything 307 2 h 55 min +# +# Plus roughly one minute for :falco-benchmarks:jmhJar, once, before the first measurement. +# +# Cross check against the scouting run as a whole: 12,1 min for 118 combinations at 5 s each scales +# to 6 x (270 / 118) x 12,1 = 166 min for 270 combinations at 30 s each. The per class derivation +# above lands at 154 min because it uses each class's own start cost instead of the average. The +# two agree to within eight percent, which is as close as an estimate of this kind gets. +# +# On the order. Ascending cost, with one deliberate exception. SectionAllocationBenchmark runs +# first because it takes three minutes, has no parameter axis and starts no server: if the jar, the +# fixture or the classpath is broken, it fails in three minutes rather than ninety. +# SetBlockContentionBenchmark is pulled forward out of cost order to second place, because it is the +# only benchmark in this suite whose subject is core scaling. Every other class runs single +# threaded and loads one core; this one saturates sixteen for eighteen minutes. Running it after two +# hours of sustained load would measure a thermally throttled machine and attribute the result to +# lock granularity. ChunkComparisonBenchmark runs last because it is half of the total. +# +# ChunkResendCostBenchmark carries one caveat this estimate cannot remove: at content = TERRAIN its +# resendViewDistance10 arm measured 765 ms per operation in the scouting run. JMH does not cut an +# operation short, so a one second iteration there completes one or two operations and overshoots to +# between 0,8 s and 1,6 s. The class's own estimate is therefore the least reliable of the six, and +# a resend row backed by two operations per iteration is a row to treat with suspicion regardless of +# what its +- says. + +# --------------------------------------------------------------------------------------------- +# Preflight +# --------------------------------------------------------------------------------------------- + +log() { printf '\n=== %s\n' "$*"; } + +run() { + if [[ $DRY_RUN -eq 1 ]]; then + printf '%q ' "$@" + printf '\n' + else + "$@" + fi +} + +check_idle() { + [[ -r /proc/loadavg ]] || return 0 + local load + load="$(cut -d' ' -f1 < /proc/loadavg)" + if awk -v l="$load" -v m="$MAX_LOAD" 'BEGIN { exit !(l > m) }'; then + echo "The one minute load average is $load, above the $MAX_LOAD this script accepts." >&2 + echo "Something else is using this machine. A measurement taken now measures it too." >&2 + echo "Stop the other work, or pass --force and record the load in conditions.txt." >&2 + exit 1 + fi +} + +record_conditions() { + local file="$OUT_DIR/conditions.txt" + { + echo "Falco JMH baseline, $DATE_STAMP" + echo + echo "Every field below is one the performance report issue template asks reporters for." + echo "A number without these is not comparable with one that has them." + echo + echo "## Run" + echo "started $(date -uIseconds)" + echo "forks $FORKS" + echo "warmup iterations $WARMUP_ITERATIONS x 1 s" + echo "measurement iters $MEASUREMENT_ITERATIONS x 1 s" + echo "profiler gc" + echo "leak arms included $WITH_LEAK_ARMS" + echo "script docs/benchmarks/full-run.sh" + echo + echo "## Source" + echo "commit $(git -C "$REPO_ROOT" rev-parse HEAD)" + echo "describe $(git -C "$REPO_ROOT" describe --tags --always --dirty 2>/dev/null || echo unknown)" + echo "working tree" + git -C "$REPO_ROOT" status --porcelain | sed 's/^/ /' || true + echo + echo "## Machine" + echo "os $(uname -sr)" + [[ -r /etc/os-release ]] && echo "distribution $(. /etc/os-release && echo "$PRETTY_NAME")" + echo "cpu $(LC_ALL=C lscpu 2>/dev/null | sed -n 's/^Model name: *//p' | head -1)" + echo "cores / threads $(LC_ALL=C lscpu 2>/dev/null | sed -n 's/^Core(s) per socket: *//p' | head -1) / $(nproc)" + echo "governor $(cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor 2>/dev/null || echo unknown)" + echo "boost $(cat /sys/devices/system/cpu/cpufreq/boost 2>/dev/null || echo unknown)" + echo "load at start $(cut -d' ' -f1-3 < /proc/loadavg 2>/dev/null || echo unknown)" + echo "memory $(LC_ALL=C free -h 2>/dev/null | sed -n '2p' || echo unknown)" + echo + echo "## JVM" + java -version 2>&1 | sed 's/^/ /' + echo + echo "Heap and any other JVM flag come from the @Fork(jvmArgsAppend) of each class." + echo "-jvmArgs is deliberately not passed: it replaces the inherited base arguments" + echo "instead of adding to them, which would be a different JVM than the annotation" + echo "describes." + echo + echo "## Idle" + echo "Answer the issue template's question here, honestly, before quoting anything:" + echo "was this machine otherwise idle for the whole run? [yes / no / unsure]" + } > "$file" + echo "conditions written to $file" +} + +# --------------------------------------------------------------------------------------------- +# The runs +# --------------------------------------------------------------------------------------------- + +jmh() { + # jmh [extra jmh flags...] + local stem="$1"; shift + local include="$1"; shift + + local cmd=(java -jar "$JAR" "$include" + -f "$FORKS" + -wi "$WARMUP_ITERATIONS" + -i "$MEASUREMENT_ITERATIONS" + -prof gc + -foe true + -rf json + -rff "$OUT_DIR/$stem.json" + "$@") + + log "$stem" + if [[ $DRY_RUN -eq 1 ]]; then + printf '%q ' "${cmd[@]}" + printf '| tee %q\n' "$OUT_DIR/$stem.human.txt" + else + "${cmd[@]}" 2>&1 | tee "$OUT_DIR/$stem.human.txt" + fi +} + +main() { + cd "$REPO_ROOT" + + if [[ $DRY_RUN -eq 0 ]]; then + [[ $FORCE -eq 1 ]] || check_idle + mkdir -p "$OUT_DIR" + fi + + log "building the benchmark jar" + run ./gradlew --quiet :falco-benchmarks:jmhJar + + JAR="$(ls "$REPO_ROOT"/falco-benchmarks/build/libs/falco-benchmarks-*-jmh.jar 2>/dev/null | head -1 || true)" + if [[ -z "$JAR" && $DRY_RUN -eq 1 ]]; then + JAR='falco-benchmarks/build/libs/falco-benchmarks--jmh.jar' + fi + if [[ -z "$JAR" ]]; then + echo "no jmh jar under falco-benchmarks/build/libs" >&2 + exit 1 + fi + + [[ $DRY_RUN -eq 0 ]] && record_conditions + + # 1 — three minutes, no server, no axis. The canary: if this fails, nothing below would have + # worked either, and it failed after three minutes instead of ninety. + jmh SectionAllocationBenchmark 'SectionAllocationBenchmark' + + # 2 — out of cost order on purpose, see the note on ordering above. Five separate processes, + # because @Threads is not an axis @Param can cross. Five separate files, because a single + # -rff would be rewritten by each following thread count; that is exactly what cost the + # scouting run four of its six result sets. + for t in "${CONTENTION_THREADS[@]}"; do + jmh "SetBlockContentionBenchmark-t$t" 'SetBlockContentionBenchmark' -t "$t" + done + + # 3 — the four content shapes. See the caveat above about resendViewDistance10 at TERRAIN. + jmh ChunkResendCostBenchmark 'ChunkResendCostBenchmark' + + # 4 — the palette break-even curve. Every one of the six sizes is a distinct statement: four of + # them are distinct entry widths, and 192 against 256 holds the width fixed at 8 to separate + # entry count from width. The scouting run resolved all six in gc.alloc.rate.norm to +- 0 B. + jmh PaletteIndirectGetBenchmark 'PaletteIndirectGetBenchmark' + + # 5 — three shares, down from four. See the javadoc of LazySectionBenchmark#emptyPercent for the + # measurement that retired the fourth. + jmh LazySectionBenchmark 'LazySectionBenchmark' + + # 6 — everything except the two copy arms that are documented as non-comparable. The exclusion + # is anchored so that minestomCopyIsolated and falcoCopyIsolated, which are the comparable + # pair, stay in. + jmh ChunkComparisonBenchmark 'ChunkComparisonBenchmark' -e '\.(minestomCopy|falcoCopy)$' + + if [[ $WITH_LEAK_ARMS -eq 1 ]]; then + # Separate file, and the file name says what it holds. The time column of this run is not a + # baseline and must not be quoted; the allocation column is. See docs/benchmarks/README.md. + jmh ChunkComparisonBenchmark-viewer-cache-leak-NOT-A-BASELINE \ + 'ChunkComparisonBenchmark\.(minestomCopy|falcoCopy)$' + fi + + log "done" + if [[ $DRY_RUN -eq 0 ]]; then + echo "results in $OUT_DIR" + echo "answer the idle question at the end of conditions.txt before quoting anything" + fi +} + +main "$@" diff --git a/docs/superpowers/HANDOFF-instance-chunk.md b/docs/superpowers/HANDOFF-instance-chunk.md new file mode 100644 index 0000000..87464d1 --- /dev/null +++ b/docs/superpowers/HANDOFF-instance-chunk.md @@ -0,0 +1,223 @@ +# Handoff: Falco's own chunk, instance and shared instance + +Written 2026-08-02 while stage 2 was still finishing, updated 2026-08-03 after all four stages +landed and both pull requests went green. Read this first if you are picking the work up in a new +session; it says where things are, what is proven, and which mistakes this project has already paid +for twice. + +## Where the work lives + +| Path | Branch | Contents | +|---|---|---| +| `Falco-worktrees/block-storage` | `feat/block-storage` | **the implementation.** Stages 1 to 3. PR #39. | +| `Falco-worktrees/shared-instance` | `feat/shared-instance` | stage 4, stacked on the branch above. PR #40. | +| `Falco-worktrees/ci-dispatch` | `ci/build-pr-dispatch` | PR #42, a manual trigger for the build. Unrelated to the storage work. | +| `Falco-worktrees/falco-bom` | `feat/falco-bom` | spec, stage 1 plan, the benchmark suite. Also carries ~38 uncommitted files of a *foreign* docs migration — not this work's, do not commit them. | +| `/mnt/projects/oss/onelitefeather/Falco` | varies | the main tree. **Another session works here.** Never write to it. | + +**#40 targets `feat/block-storage`, not `main`.** They merge in that order, and a change that has to +reach both goes into `block-storage` first and is then merged forward. + +Everything below refers to the `block-storage` worktree unless stated otherwise. + +## The documents, in reading order + +1. `docs/superpowers/research/2026-08-01-instance-chunk-research.md` — the research, 531 lines. + Chapter 9 lists the 19 of 44 claims that an adversarial pass killed. Read it before trusting any + assertion about Minestom that is not in a test. **It exists only in the `falco-bom` worktree**, + not in this one and not on any branch that has an open pull request, so nothing currently on its + way to `main` carries it. Everything below points back at it; if that branch is dropped, the + reasoning behind every design decision here goes with it. +2. `docs/superpowers/specs/2026-08-01-falco-instance-chunk-design.md` — the spec. Four stages, + 22 user stories in EARS syntax, 9 non-functional requirements. Chapter 2 is the measurement table + every architectural choice points back at. +3. `docs/superpowers/plans/2026-08-01-falco-block-storage.md` — stage 1, with `## Stage 1 result`. +4. `docs/superpowers/plans/2026-08-02-falco-lazy-sections.md` — stage 2, ten tasks. +5. `docs/superpowers/plans/2026-08-02-falco-instance-facade.md` — stage 3, twelve tasks. +6. `docs/superpowers/plans/2026-08-02-falco-shared-instance.md` — stage 4, eight tasks (in the + `shared-instance` worktree). +7. `.superpowers/sdd/*/progress.md` — the ledgers, one directory per stage. One line per commit, + written by the implementers themselves. **These are the recovery map**; trust them and `git log` + over any recollection. + +## State + +**Stage 1 — done, reviewed, merged into the branch.** `FalcoChunk` moved from `extends DynamicChunk` +to `extends Chunk` holding a `BlockStorage`. The seam costs one object, 24 bytes per chunk. A final +whole-branch review found five Important defects, all fixed — two were real regressions no test saw +(a dropped `requireNonNullElse(…, Block.AIR)` and both biome registry guards). + +**Stage 2 — done.** All ten tasks, acceptance recorded in `## Stage 2 result` at the end of the stage 2 +plan. Empty sections share one flyweight, the generator stages through `view(int)` and packs on commit +behind a guard, heightmaps are built on demand, and the two block maps became one plus a counter. +A fresh chunk fell from 192 objects / 6 848 B to **25 / 840**, which is −87.7 %; a filled chunk saves +104 B and nothing more, because the flyweight pays for sections that hold nothing. + +**Stage 2 — reviewed.** The final whole-branch review found four defects, all fixed in one wave +(`.superpowers/sdd/2026-08-02-falco-lazy-sections/final-review-fix-report.md`). Two were real and +neither had a test: materialising a section was an unsynchronised read-modify-write reachable from +three lock-free Minestom call sites and could lose a block silently, and the generator wrote its +special blocks inside the commit loop, which latched both heightmaps over a half-committed chunk for +the life of the chunk. The other two were figures that had gone stale, one of them in the table below. + +**Stage 3 — done and reviewed.** The facade split of `FalcoInstance`, which had grown to 1 119 lines +doing registry, loading, block writing, generation and persistence, into four parts it delegates to, +plus lifecycle listeners and the viewer-cache cleanup. `InstanceFacadeTest` pins that it declares +exactly four instance fields, so a fifth kills the test. The stage also moved `FalcoLightingChunk` +from `DynamicChunk` onto `FalcoChunk` (US-3.06) — the point the whole rewrite was aiming at, and the +change that broke binary compatibility, see below. Acceptance in `## Stage 3 result`, ledger at +`.superpowers/sdd/2026-08-02-falco-instance-facade/progress.md`. + +**Stage 4 — done and reviewed.** `FalcoSharedInstance`, with the constructor guard and the save path +that reports through the returned future alone. Acceptance in `## Stage 4 result`, ledger at +`.superpowers/sdd/2026-08-02-falco-shared-instance/progress.md`. + +**Both pull requests are green and out of draft** as of 2026-08-03 14:00, on all three runners. +Neither has been reviewed by a human yet. + +## What is measured, and what is not + +**Citable** — JOL and counting tests are deterministic and were taken on a loaded machine without harm: + +| | | +|---|---| +| fresh chunk, Minestom | 192 objects, 6 848 B | +| fresh chunk, Falco after stage 2 | **25 objects, 840 B** | +| materialisation: fresh chunk / pure read | 0 / 0 sections | +| one `setBlock` at y=64 | 10 sections — the heightmap descent, not the write | +| write order y=200 then y=−64 / reverse | 18 / 3 — a factor of six | +| `getSections()` | 24 — it is a write in disguise | +| generation of y=−64..0 | 4 of 24 | +| empty section share, real generated overworld | 62.24 % (441 finished chunks around one spawn) | +| palette break-even, indirect against direct | between 192 and 224 entries | +| Minestom's viewer cache leak | 1 entry per chunk construction, 257 B, never removed | + +If you find **32 objects / 2 088 B** for the fresh Falco chunk in an older task report, it is the same +measurement taken with tasks 2 and 3 in place and tasks 7 and 8 not yet written. The difference is the +four objects of the two heightmaps and the three of the second block map. `ChunkFootprintTest` says +which is current; it is the only thing that does. + +**Not citable** — every timing figure taken during this work. The machine ran at load 4.4 to 7.0 +throughout (a Minecraft client, an IDE and several agent sessions). They establish direction, never +magnitude. Among them: the 6.2×/7.3× on `setBlock` contention, the 765 ms / 86.5 MB chunk resend, +the 24× cost of `optimize()`. + +**The full JMH run has never happened.** `docs/benchmarks/full-run.sh` (in the `falco-bom` worktree) +takes 2 h 35 min at three forks and refuses to start above load 1.5. It needs an idle machine. Until +it has run, no timing figure from this work belongs in the README or the wiki. + +## The mistake this project keeps making + +Six times in one session, a check did something other than what it claimed. Every time the result +looked plausible first: + +1. The census counted a void hub world and reported it as an overworld — 99.6 % against the real 62.2 %. +2. A copy benchmark measured Minestom's viewer cache leak instead of a copy, and reported Falco as + forty times faster than code that does strictly more work. +3. `BlockStorageTest` stayed green with the `- minSection` term deleted from every method, because + all five cases used y = 0..3 where the term contributes nothing. +4. The equivalence check materialised the chunk whose footprint was about to be measured, so every + number after it measured the check. This one hid the entire stage 2 saving. +5. Stage 1 dropped two Minestom guards and no test noticed, because no test ever touched a biome. +6. The stage 2 task briefs carried materialisation counts of 1/1/17 that measurement corrected to + 0/1/10. + +**Therefore, in every agent brief:** *Would your test still be green without the implementation?* +and *Does your measurement measure itself?* Both questions have earned their place. Implementers now +prove their tests bite by mutation, and several have caught their own briefs being wrong. + +## Traps that cost time + +- **The Minestom clone at `/mnt/projects/oss/minestom/Minestom` is ten months stale.** It caused + eleven false findings in the research. The canonical reference is the unpacked sources jar of the + pinned version, at + `/tmp/claude-1000/-mnt-projects-oss-onelitefeather-Falco/34edb948-9dfe-4540-9666-9e29f0d44d7b/scratchpad/minestom-src` + (re-unpack from `~/.gradle/caches/…/minestom-2026.06.20-26.1.2-sources.jar` if the scratchpad is gone). +- **`getSections()`, `getSection(int)` and `Heightmap#getHeight` materialise.** For reading only, + `BlockStorage` has `view(int)`, `views()` and `materialisedSections()`. +- **`Palette#compare` cannot compare content across a mode change** — it compares the `count` field, + which carries the value itself in single-value mode. +- **`optimize()` is not free and not always useful.** It gives up above `maxBitsPerEntry = 8`, so on + a wide palette it charges full price for nothing. `PaletteCompaction` asks first. +- **Long background runs do not survive a session change.** Three died mid-work here, each with + finished but uncommitted changes. Recovery was possible only through `git status` and the reports. + Keep runs to two tasks, and make implementers write the ledger after every commit. +- **Region file size says nothing about terrain density.** Anvil pads every chunk to whole 4096-byte + sectors; a 4.3 MB file held 601 KB of payload. + +## What the build and the CI do that will surprise you + +Four things cost most of an afternoon on 2026-08-03. None is in the code this work wrote. + +**A conflicted pull request produces no CI run at all.** Not a failed one, not a skipped one — none. +GitHub cannot form `refs/pull/N/merge` for a PR that conflicts with its base, and no run is created. +When `272cb0b3` landed on `main` at 21:07 UTC and put `FalcoLightingChunk.java` into conflict, both +PRs sat without CI for fifteen hours and the Actions page said nothing. The symptom looks exactly +like a disabled repository or an exhausted quota, and both were checked before the real cause was +found. **If runs stop appearing, check `gh pr view N --json mergeable` first.** + +**`:falco-benchmarks:test` hangs on macOS and is skipped there.** The test JVM starts and no test +ever reports; the module writes zero-byte result files, the job goes silent for as long as you let +it, and the runner terminates orphan `java` processes at the end. It is the only module whose test +JVM runs with `allowAttachSelf`, `EnableDynamicAgentLoading`, `jol.magicFieldOffset` and a 4 GB heap +on a 7 GB runner, which is what jol needs to measure retained size. **Which of those hangs on arm64 +is not diagnosed.** `-Pfalco.macOsFootprintTests` forces the task back on for whoever picks it up; +`docs/benchmarks/README.md` has the observation and what the skip costs. + +**`ChunkFootprintTest` has a rare flake, and its shape is worth knowing.** One ubuntu run reported +`-2 objects of [B` where a difference of zero was expected. The value is the set of objects that +exist because the chunk exists, computed as (chunk + instance) minus (instance alone) from two +separate walks — and a set has no negative cardinality, so the two walks did not see the same +instance state. Reproduced neither locally (8 runs, 3 of them pinned to two cores) nor on the rerun +of the same job. Recorded as a comment on PR #39. The tempting wrong fix is to loosen the assertion; +the right one is to make both walks see the same state and to report a negative difference as an +invalid measurement rather than compare it. + +**japicmp exceptions live in `gradle/api-breaks.properties` and expire on their own.** The file lists +each deliberately accepted break with its reason and names the baseline it was judged against; the +build fails if that drifts from `apiBaselineVersion`, so an exception cannot outlive the release +that absorbs it. Currently one entry: `FalcoLightingChunk` became `final` under US-3.06. Two of the +three findings japicmp reports for that class are wrong — `setBlock(…, Placement, Destroy)` and +`tick(long)` are still public on `FalcoChunk` and reach callers by inheritance, which japicmp cannot +see because that class is in another module and `ignoreMissingClasses` is on. + +## Open defect, found during the merge and deliberately not fixed + +`FalcoChunk#tick(long)` iterates `this.entries` with no lock, and `Int2ObjectOpenHashMap` is not +thread-safe. A concurrent `setBlock` that rehashes the map while the tick thread walks it can yield +garbage or spin. The tick thread never holds the chunk lock — `ThreadDispatcher` registers the chunk +as a `Tickable` and `TickThread` calls it under its own lock — and Minestom's `Chunk#tick` contract +says outright that the method "doesn't necessary have to be thread-safe". + +**Upstream `DynamicChunk` has the identical race** with its `tickableMap` (`DynamicChunk.java:185-186`), +so this is inherited rather than introduced by the storage rewrite. ArchUnit cannot see it: the field +is `final`, so `sharedStateIsSafelyPublished` skips it by construction. + +Fixing it is a design decision — take the read lock in `tick`, make the map concurrent, or confine +writes to the chunk's tick thread — and each option has a cost on a path that runs for every chunk +every tick. It belongs to stage 3, which owns the lifecycle, and it is recorded here so that the next +reader meets it as a known open item rather than as a surprise. + +## How to continue + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +git log --oneline 6ec6973..HEAD # everything the four stages did +cat .superpowers/sdd/*/progress.md # the ledgers, in stage order +./gradlew build # not :module:test — see below +``` + +**Run `./gradlew build`, not the individual test tasks.** A whole session ran `:module:test` only +and never saw that `:falco-light:checkApiCompatibility` had been failing since stage 3. The test +tasks are green while the build is red, and the difference is exactly the checks that guard the +published API. + +`ChunkFootprintTest` was deliberately red from stage 1 until task 9 of stage 2 reset its +expectation. If it is red now, check the ledger before assuming a regression — and if it says +`-2 objects`, it is the flake described above, not a defect in the code. + +All four stages are implemented. What is left is listed under the open items above: the tick race, +the macOS hang, the footprint flake, and the JMH baseline that has still never run. Should more +implementation follow, the shape that worked here was: one plan per stage under +`docs/superpowers/plans/`, tasks with full code and TDD cycles, then a workflow of at most two tasks +per run with a fresh implementer and a fresh reviewer each. diff --git a/docs/superpowers/plans/2026-08-01-falco-block-storage.md b/docs/superpowers/plans/2026-08-01-falco-block-storage.md new file mode 100644 index 0000000..2716664 --- /dev/null +++ b/docs/superpowers/plans/2026-08-01-falco-block-storage.md @@ -0,0 +1,1031 @@ +# Falco Block Storage — Stage 1 Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Give Falco a chunk that owns its block storage behind an interface, so that the memory layout becomes replaceable without touching a chunk class and the lifecycle stops being tied to `DynamicChunk` by inheritance. + +**Architecture:** A bridge. `FalcoChunk` moves from `extends DynamicChunk` to `extends Chunk` and holds a `BlockStorage`. The abstraction side keeps lifecycle, viewers, heightmaps and packet building; the implementation side owns blocks and biomes. Stage 1 ships exactly one implementation, `SectionBlockStorage`, which stores Minestom `Section` objects eagerly — the same layout as today. **Stage 1 must therefore measure identical to `DynamicChunk`.** That is the point: it proves the bridge costs nothing before stage 2 changes the layout behind it. + +**Tech Stack:** Java 25, Gradle, JUnit 5, Cyano (Minestom test extension), JMH + JOL for measurement, fastutil. + +## Global Constraints + +Copied verbatim from the spec (`docs/superpowers/specs/2026-08-01-falco-instance-chunk-design.md`): + +- **NFR-001** — compile and run against the pinned Minestom version without reflection, `--add-opens` or an open module. +- **NFR-002** — only language and JDK features final in Java 25. No preview, no incubator. +- **NFR-003** — if a performance claim is published, a JMH or JOL measurement in this repository supports it, stated with its conditions. +- **NFR-004** — while a comparison benchmark runs, it fails rather than reports a number if the two sides disagree. +- **NFR-005** — when a chunk read fails, the failure reaches the caller instead of being reported as an absent chunk. +- **NFR-006** — while a block is written, the lock held is the lock of the chunk it touches, not a monitor over the instance. +- **NFR-007** — the chunk allocates no object per block read on any path. +- **NFR-009** — every new public type carries `@ApiStatus.Experimental`. + +Repository conventions, non-negotiable: + +- **Source and Javadoc are English**, and Javadoc *justifies* decisions in `

` paragraphs and `

` sections. Every type carries `@author TheMeinerLP`, `@version`, `@since 0.4.0`. Model: `falco-light/src/main/java/net/onelitefeather/falco/light/ChunkLightService.java`. +- **Gradle files stay comment-free.** +- **Minestom reference is the pinned sources jar**, unpacked at `/tmp/claude-1000/-mnt-projects-oss-onelitefeather-Falco/34edb948-9dfe-4540-9666-9e29f0d44d7b/scratchpad/minestom-src/`. The clone at `/mnt/projects/oss/minestom/Minestom` is ten months stale and must not be used. +- Work happens in the worktree `/mnt/projects/oss/onelitefeather/Falco-worktrees/falco-bom`, on branch `feat/falco-bom`. + +## What `Chunk` demands + +`Chunk` is `public abstract` and implements `Block.Getter, Block.Setter, Biome.Getter, Biome.Setter, Viewable, Tickable, Taggable, Snapshotable`. A subclass must supply these eleven: + +```java +protected abstract void setBlock(int x, int y, int z, Block block, + @Nullable BlockHandler.Placement placement, + @Nullable BlockHandler.Destroy destroy); // :99 +public abstract List
getSections(); // :103 +public abstract Section getSection(int section); // :105 +public abstract Heightmap motionBlockingHeightmap(); // :107 +public abstract Heightmap worldSurfaceHeightmap(); // :108 +public abstract void loadHeightmapsFromNBT(CompoundBinaryTag heightmaps); // :109 +public abstract void tick(long time); // :125 +public abstract SendablePacket getFullDataPacket(); // :141 +public abstract Chunk copy(Instance instance, int chunkX, int chunkZ); // :153 +public abstract void reset(); // :158 +public abstract void invalidate(); // :315 +``` + +`DynamicChunk` is the reference implementation for all of them. Read it before Task 3; do not invent behaviour that it already defines. + +## File Structure + +| File | Responsibility | +|---|---| +| `falco-instance/src/main/java/net/onelitefeather/falco/instance/BlockStorage.java` | **Create.** The implementation side of the bridge: blocks and biomes of one chunk, addressed in chunk-local coordinates. Knows nothing about lifecycle, viewers, packets or heightmaps. | +| `.../instance/SectionBlockStorage.java` | **Create.** The stage 1 implementation. Holds Minestom `Section` objects eagerly, exactly as `DynamicChunk` does today. | +| `.../instance/FalcoChunk.java` | **Rewrite.** From `extends DynamicChunk` (129 lines, no fields) to `extends Chunk` holding a `BlockStorage`. | +| `falco-instance/src/test/java/.../instance/BlockStorageTest.java` | **Create.** Contract tests for the interface, run against every implementation. | +| `falco-instance/src/test/java/.../instance/FalcoChunkEquivalenceTest.java` | **Create.** Position-by-position equivalence against `DynamicChunk` (US-1.03). | +| `falco-instance/src/test/java/.../instance/FalcoChunkInContainerTest.java` | **Create.** The chunk loads and unloads inside a plain `InstanceContainer` (US-1.05). | + +`falco-benchmarks` already carries `ChunkComparisonBenchmark` and `ChunkFootprintTest`; both compare `FalcoChunk` against `DynamicChunk` and will start reporting the bridge automatically. They are the regression net for this stage and must be re-run at the end. + +--- + +### Task 1: The `BlockStorage` interface + +**Files:** +- Create: `falco-instance/src/main/java/net/onelitefeather/falco/instance/BlockStorage.java` +- Test: `falco-instance/src/test/java/net/onelitefeather/falco/instance/BlockStorageTest.java` + +**Interfaces:** +- Consumes: nothing. +- Produces: `BlockStorage` with `Block getBlock(int, int, int, Block.Getter.Condition)`, `void setBlock(int, int, int, Block)`, `RegistryKey getBiome(int, int, int)`, `void setBiome(int, int, int, RegistryKey)`, `List
sections()`, `Section section(int)`, `int sectionCount()`, `BlockStorage copy()`, `void clear()`. Tasks 2 and 3 depend on exactly these names. + +- [ ] **Step 1: Write the failing test** + +Create `BlockStorageTest.java`. It is written against the interface so that stage 2's implementation inherits it unchanged: + +```java +package net.onelitefeather.falco.instance; + +import net.minestom.server.MinecraftServer; +import net.minestom.server.instance.block.Block; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotSame; + +@DisplayName("The block storage of a chunk") +class BlockStorageTest { + + private static final int SECTIONS = 24; + private static final int MIN_SECTION = -4; + + @BeforeAll + static void server() { + if (MinecraftServer.process() == null) { + MinecraftServer.init(); + } + } + + private static BlockStorage storage() { + return new SectionBlockStorage(MIN_SECTION, SECTIONS); + } + + @Test + @DisplayName("returns air for a position nothing was written to") + void testEmptyReadsAir() { + assertEquals(Block.AIR, storage().getBlock(0, 0, 0, Block.Getter.Condition.NONE)); + } + + @Test + @DisplayName("returns what was written, at the position it was written to") + void testWriteThenRead() { + final BlockStorage storage = storage(); + + storage.setBlock(1, 2, 3, Block.STONE); + + assertEquals(Block.STONE, storage.getBlock(1, 2, 3, Block.Getter.Condition.NONE)); + assertEquals(Block.AIR, storage.getBlock(1, 2, 4, Block.Getter.Condition.NONE)); + } + + @Test + @DisplayName("holds one section per section of the chunk") + void testSectionCount() { + assertEquals(SECTIONS, storage().sectionCount()); + assertEquals(SECTIONS, storage().sections().size()); + } + + @Test + @DisplayName("copies without sharing storage with the original") + void testCopyIsIndependent() { + final BlockStorage original = storage(); + original.setBlock(1, 2, 3, Block.STONE); + + final BlockStorage copy = original.copy(); + copy.setBlock(1, 2, 3, Block.DIRT); + + assertNotSame(original, copy); + assertEquals(Block.STONE, original.getBlock(1, 2, 3, Block.Getter.Condition.NONE)); + assertEquals(Block.DIRT, copy.getBlock(1, 2, 3, Block.Getter.Condition.NONE)); + } + + @Test + @DisplayName("reads air everywhere after being cleared") + void testClear() { + final BlockStorage storage = storage(); + storage.setBlock(1, 2, 3, Block.STONE); + + storage.clear(); + + assertEquals(Block.AIR, storage.getBlock(1, 2, 3, Block.Getter.Condition.NONE)); + } +} +``` + +- [ ] **Step 2: Run the test to verify it fails** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/falco-bom +./gradlew :falco-instance:test --tests "*BlockStorageTest*" +``` + +Expected: compilation failure — `BlockStorage` and `SectionBlockStorage` do not exist. + +- [ ] **Step 3: Write the interface** + +Create `BlockStorage.java`. The Javadoc must state *why* the type exists, in the style of `ChunkLightService`: + +```java +package net.onelitefeather.falco.instance; + +import net.minestom.server.instance.Section; +import net.minestom.server.instance.block.Block; +import net.minestom.server.registry.RegistryKey; +import net.minestom.server.world.biome.Biome; +import org.jetbrains.annotations.ApiStatus; + +import java.util.List; + +/** + * The {@link BlockStorage} interface is the implementation side of the chunk of Falco. + *

+ * A chunk of Minestom keeps its blocks in a field its subclasses inherit, which means that a chunk + * which wants a different memory layout has to be a different chunk class. That is why + * {@code FalcoChunk} and {@code FalcoLightingChunk} cannot be combined today: both of them extend + * {@code DynamicChunk}, and a class has one superclass. Moving the storage behind this interface + * turns those two branches into two parts that compose. + *

+ *

+ * The split is drawn where the two sides stop needing each other. Everything that is about the + * identity of a chunk stays outside: its position, its lifecycle, its viewers, its heightmaps and + * the packet it sends. Everything that is about where a block physically sits lives here. An + * implementation of this interface therefore never needs an {@code Instance}, and the chunk never + * needs to know whether the blocks below it are sections, a packed array or something off heap. + *

+ *

+ * Coordinates are chunk-local: {@code x} and {@code z} are {@code 0} to {@code 15}, and {@code y} is + * an absolute world height, because that is the form both {@code Chunk} and the anvil format use and + * translating twice would be a second place to get it wrong. + *

+ *

+ * Implementations are not thread-safe on their own. The caller holds the lock of the chunk, which + * {@code Chunk#lockWriteLock()} and {@code Chunk#lockReadLock()} provide. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ApiStatus.Experimental +public interface BlockStorage { + + /** + * Reads the block at a position. + * + * @param x the chunk-local block X, {@code 0} to {@code 15} + * @param y the absolute block Y + * @param z the chunk-local block Z, {@code 0} to {@code 15} + * @param condition what the caller is willing to accept, as {@code Block.Getter} defines it + * @return the block, or {@code null} if the condition excludes it + */ + Block getBlock(int x, int y, int z, Block.Getter.Condition condition); + + /** + * Writes a block to a position. + * + * @param x the chunk-local block X, {@code 0} to {@code 15} + * @param y the absolute block Y + * @param z the chunk-local block Z, {@code 0} to {@code 15} + * @param block the block to write + */ + void setBlock(int x, int y, int z, Block block); + + /** + * Reads the biome at a position. + * + * @param x the chunk-local block X, {@code 0} to {@code 15} + * @param y the absolute block Y + * @param z the chunk-local block Z, {@code 0} to {@code 15} + * @return the biome + */ + RegistryKey getBiome(int x, int y, int z); + + /** + * Writes a biome to a position. + * + * @param x the chunk-local block X, {@code 0} to {@code 15} + * @param y the absolute block Y + * @param z the chunk-local block Z, {@code 0} to {@code 15} + * @param biome the biome to write + */ + void setBiome(int x, int y, int z, RegistryKey biome); + + /** + * Hands out the sections of this storage, from the bottom one upwards. + *

+ * This is a boundary method. Minestom demands {@code Section} objects for packet serialisation, + * for its light engine and for the anvil writer, so an implementation which does not store them + * has to materialise them here. Calling this is therefore the one operation that can undo + * whatever an implementation saved by not holding them, which is why the chunk calls it only + * where Minestom leaves no choice. + *

+ * + * @return the sections of this storage + */ + List
sections(); + + /** + * Hands out one section of this storage. + * + * @param section the index of the section, counted from the bottom one + * @return the section + */ + Section section(int section); + + /** + * Reports how many sections this storage spans. + * + * @return the amount of sections + */ + int sectionCount(); + + /** + * Creates a storage holding the same blocks and biomes as this one, sharing nothing with it. + * + * @return the copy + */ + BlockStorage copy(); + + /** + * Resets this storage to the state it had when it was created. + */ + void clear(); +} +``` + +- [ ] **Step 4: Run the test to verify it still fails, for the right reason** + +```bash +./gradlew :falco-instance:test --tests "*BlockStorageTest*" +``` + +Expected: still a compilation failure, now only about `SectionBlockStorage`. If it complains about anything in `BlockStorage`, fix that before moving on. + +- [ ] **Step 5: Commit the interface** + +```bash +git add falco-instance/src/main/java/net/onelitefeather/falco/instance/BlockStorage.java \ + falco-instance/src/test/java/net/onelitefeather/falco/instance/BlockStorageTest.java +git commit -m "feat(instance): introduce BlockStorage, the implementation side of the chunk" +``` + +--- + +### Task 2: `SectionBlockStorage` + +**Files:** +- Create: `falco-instance/src/main/java/net/onelitefeather/falco/instance/SectionBlockStorage.java` +- Test: `BlockStorageTest.java` (from Task 1, unchanged) + +**Interfaces:** +- Consumes: `BlockStorage` from Task 1. +- Produces: `SectionBlockStorage(int minSection, int sectionCount)` and `SectionBlockStorage(int minSection, List
sections)`. Task 3 constructs both. + +**Reference:** `DynamicChunk#getBlock` (`:197`), `#setBlock` (`:74`) and `#setBiome` (`:137`) in the pinned sources. Copy their coordinate arithmetic rather than re-deriving it — `CoordConversion` holds the index helpers, and getting the section index wrong is silent, not loud. + +- [ ] **Step 1: Write the implementation** + +Eager sections, the same layout `DynamicChunk` has today. Stage 2 replaces this class; stage 1 must not change behaviour. + +```java +package net.onelitefeather.falco.instance; + +import net.minestom.server.MinecraftServer; +import net.minestom.server.coordinate.CoordConversion; +import net.minestom.server.instance.Section; +import net.minestom.server.instance.block.Block; +import net.minestom.server.registry.DynamicRegistry; +import net.minestom.server.registry.RegistryKey; +import net.minestom.server.world.biome.Biome; +import org.jetbrains.annotations.ApiStatus; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; + +/** + * The {@link SectionBlockStorage} class stores the blocks of a chunk in Minestom {@link Section} + * objects, one per sixteen blocks of height, allocated when the storage is created. + *

+ * This is deliberately the layout {@code DynamicChunk} already has, and it is the first + * implementation on purpose: it makes the bridge measurable before the bridge changes anything. A + * chunk built on this storage has to be indistinguishable from a {@code DynamicChunk} in both time + * and bytes, and {@code ChunkComparisonBenchmark} together with {@code ChunkFootprintTest} is what + * says whether it is. A layout that saves memory is the subject of the next stage; if this one + * already differed, the difference of that next stage could not be attributed to it. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ApiStatus.Experimental +public final class SectionBlockStorage implements BlockStorage { + + private static final DynamicRegistry BIOME_REGISTRY = MinecraftServer.getBiomeRegistry(); + + private final int minSection; + private final List
sections; + + /** + * Creates a storage of empty sections. + * + * @param minSection the index of the bottom section of the chunk + * @param sectionCount the amount of sections the chunk spans + */ + public SectionBlockStorage(int minSection, int sectionCount) { + final Section[] created = new Section[sectionCount]; + + Arrays.setAll(created, index -> new Section()); + this.minSection = minSection; + this.sections = List.of(created); + } + + /** + * Creates a storage which takes over the given sections. + * + * @param minSection the index of the bottom section of the chunk + * @param sections the sections, from the bottom one upwards + */ + public SectionBlockStorage(int minSection, List
sections) { + this.minSection = minSection; + this.sections = List.copyOf(sections); + } + + @Override + public Block getBlock(int x, int y, int z, Block.Getter.Condition condition) { + final Section section = section(CoordConversion.globalToChunk(y) - this.minSection); + final int stateId = section.blockPalette() + .get(CoordConversion.globalToSectionRelative(x), + CoordConversion.globalToSectionRelative(y), + CoordConversion.globalToSectionRelative(z)); + + return Block.fromStateId(stateId); + } + + @Override + public void setBlock(int x, int y, int z, Block block) { + section(CoordConversion.globalToChunk(y) - this.minSection).blockPalette() + .set(CoordConversion.globalToSectionRelative(x), + CoordConversion.globalToSectionRelative(y), + CoordConversion.globalToSectionRelative(z), block.stateId()); + } + + @Override + public RegistryKey getBiome(int x, int y, int z) { + final Section section = section(CoordConversion.globalToChunk(y) - this.minSection); + final int id = section.biomePalette() + .get(CoordConversion.globalToSectionRelative(x) / Section.BIOME_SIZE, + CoordConversion.globalToSectionRelative(y) / Section.BIOME_SIZE, + CoordConversion.globalToSectionRelative(z) / Section.BIOME_SIZE); + + return BIOME_REGISTRY.getKey(id); + } + + @Override + public void setBiome(int x, int y, int z, RegistryKey biome) { + section(CoordConversion.globalToChunk(y) - this.minSection).biomePalette() + .set(CoordConversion.globalToSectionRelative(x) / Section.BIOME_SIZE, + CoordConversion.globalToSectionRelative(y) / Section.BIOME_SIZE, + CoordConversion.globalToSectionRelative(z) / Section.BIOME_SIZE, + BIOME_REGISTRY.getId(biome)); + } + + @Override + public List
sections() { + return this.sections; + } + + @Override + public Section section(int section) { + return this.sections.get(section); + } + + @Override + public int sectionCount() { + return this.sections.size(); + } + + @Override + public BlockStorage copy() { + final List
copied = new ArrayList<>(this.sections.size()); + + for (Section section : this.sections) { + copied.add(section.clone()); + } + return new SectionBlockStorage(this.minSection, copied); + } + + @Override + public void clear() { + for (Section section : this.sections) { + section.clear(); + } + } +} +``` + +- [ ] **Step 2: Verify the API against the pinned sources before running anything** + +Every name used above must exist. Check each one and correct the code if it does not: + +```bash +S=/tmp/claude-1000/-mnt-projects-oss-onelitefeather-Falco/34edb948-9dfe-4540-9666-9e29f0d44d7b/scratchpad/minestom-src +grep -nE "globalToChunk|globalToSectionRelative" $S/net/minestom/server/coordinate/CoordConversion.java | head +grep -nE "blockPalette|biomePalette|BIOME_SIZE|public void clear|public Section clone" $S/net/minestom/server/instance/Section.java +grep -nE "public .*getKey|public .*getId" $S/net/minestom/server/registry/DynamicRegistry.java | head +grep -n "getBiome\|setBiome" $S/net/minestom/server/instance/DynamicChunk.java | head +``` + +If `DynamicChunk` divides biome coordinates differently than the code above, **follow `DynamicChunk`** — it is the behaviour the equivalence test in Task 4 compares against. + +- [ ] **Step 3: Run the tests** + +```bash +./gradlew :falco-instance:test --tests "*BlockStorageTest*" +``` + +Expected: PASS, all five. + +- [ ] **Step 4: Commit** + +```bash +git add falco-instance/src/main/java/net/onelitefeather/falco/instance/SectionBlockStorage.java +git commit -m "feat(instance): store blocks in sections behind BlockStorage" +``` + +--- + +### Task 3: `FalcoChunk` over the bridge + +**Files:** +- Rewrite: `falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoChunk.java` +- Test: covered by Task 4 + +**Interfaces:** +- Consumes: `BlockStorage`, `SectionBlockStorage` from Tasks 1–2. +- Produces: `FalcoChunk(Instance, int, int)`, `FalcoChunk(Instance, int, int, BlockStorage)`, `markLoaded()`, `markUnloaded()`, `storage()`. + +**Reference:** `DynamicChunk` in the pinned sources implements all eleven abstract members. Read it in full first. Everything that is not about *where blocks live* — the entries map, the tickable map, the heightmaps, the cached packet, `tick`, `getFullDataPacket`, `reset`, `invalidate`, `loadHeightmapsFromNBT` — is carried over as it stands. Only block and biome access is redirected to the storage. + +- [ ] **Step 1: Read the reference and write down what carries over** + +```bash +S=/tmp/claude-1000/-mnt-projects-oss-onelitefeather-Falco/34edb948-9dfe-4540-9666-9e29f0d44d7b/scratchpad/minestom-src +sed -n '1,120p' $S/net/minestom/server/instance/DynamicChunk.java +``` + +Note especially: `setBlock` maintains `entries` and `tickableMap` and refreshes both heightmaps; `getBlock` guards the entries lookup by condition; `createChunkPacket` runs under the read lock. + +- [ ] **Step 2: Write the members that change** + +These are the ones where the bridge is visible. Everything not listed here is **carried over from `DynamicChunk` unchanged** — copy the body across, keep its Javadoc intent, and do not redesign it: `motionBlockingHeightmap`, `worldSurfaceHeightmap`, `loadHeightmapsFromNBT`, `tick`, `getFullDataPacket`, `createChunkPacket`, `reset`, `invalidate`, and the viewer and tag plumbing. + +```java +public class FalcoChunk extends Chunk { + + private final BlockStorage storage; + + protected final Int2ObjectOpenHashMap entries = new Int2ObjectOpenHashMap<>(0); + protected final Int2ObjectOpenHashMap tickableMap = new Int2ObjectOpenHashMap<>(0); + + protected Heightmap motionBlocking = new MotionBlockingHeightmap(this); + protected Heightmap worldSurface = new WorldSurfaceHeightmap(this); + + private final CachedPacket chunkCache = new CachedPacket(this::createChunkPacket); + + public FalcoChunk(Instance instance, int chunkX, int chunkZ) { + super(instance, chunkX, chunkZ, true); + // Must be built here, not in a field initialiser: the super constructor is what computes + // minSection and maxSection, and the storage is sized from them. + this.storage = new SectionBlockStorage(minSection, maxSection - minSection); + } + + public FalcoChunk(Instance instance, int chunkX, int chunkZ, BlockStorage storage) { + super(instance, chunkX, chunkZ, true); + this.storage = storage; + } + + public BlockStorage storage() { + return this.storage; + } + + @Override + public List
getSections() { + return this.storage.sections(); + } + + @Override + public Section getSection(int section) { + return this.storage.section(section - minSection); + } + + @Override + public Chunk copy(Instance instance, int chunkX, int chunkZ) { + assertReadLock(); + final FalcoChunk copy = new FalcoChunk(instance, chunkX, chunkZ, this.storage.copy()); + + copy.entries.putAll(this.entries); + // DynamicChunk#copy copies only entries, so a copied chunk stops ticking. That omission is + // a bug the previous FalcoChunk already fixed, and it must not return with the rewrite. + copy.tickableMap.putAll(this.tickableMap); + return copy; + } + + public void markLoaded() { + onLoad(); + } + + public void markUnloaded() { + unload(); + } +} +``` + +`getBlock` and `setBlock` keep every line of bookkeeping `DynamicChunk` does — the entries map, the tickable map, both heightmap refreshes, the packet invalidation — and change only where the block itself comes from and goes to: + +```java +@Override +public void setBlock(int x, int y, int z, Block block, + @Nullable BlockHandler.Placement placement, + @Nullable BlockHandler.Destroy destroy) { + assertWriteLock(); + // ... every guard and every bookkeeping line of DynamicChunk#setBlock, unchanged ... + this.storage.setBlock(x, y, z, block); // was: getSectionAt(y).blockPalette().set(...) + // ... the entries/tickableMap maintenance and both heightmap refreshes, unchanged ... +} + +@Override +public @Nullable Block getBlock(int x, int y, int z, Condition condition) { + assertReadLock(); + // ... the entries lookup and its condition guard, exactly as DynamicChunk has it ... + return this.storage.getBlock(x, y, z, condition); // was: the palette read +} +``` + +**Note the index shift in `getSection`.** `Chunk#getSection(int)` takes a section index in world terms, which can be negative; `BlockStorage#section(int)` takes an offset from the bottom section. Subtracting `minSection` is the translation, and getting it wrong is silent — the equivalence test of Task 4 is what catches it. + +The class Javadoc must be rewritten. The old one says *"deliberately adds no storage, no light handling and no packet handling of its own"*, which stops being true here. State instead that the storage moved behind an interface, and why: two subclasses of `DynamicChunk` could not be combined, and a class has one superclass. + +- [ ] **Step 3: Compile** + +```bash +./gradlew :falco-instance:compileJava +``` + +Expected: BUILD SUCCESSFUL. An "does not override abstract method" error means one of the eleven is missing — add it from `DynamicChunk`. + +- [ ] **Step 4: Run the existing instance tests** + +```bash +./gradlew :falco-instance:test +``` + +Expected: PASS. `FalcoChunkTest`, `FalcoInstanceTest`, `FalcoInstanceGeneratorTest`, `FalcoInstanceUnloadTest` and `FalcoInstanceLoadRaceTest` exercise the chunk through the instance and are the first real net. If one fails, the rewrite changed behaviour — fix the rewrite, not the test. + +- [ ] **Step 5: Commit** + +```bash +git add falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoChunk.java +git commit -m "refactor(instance): hold block storage instead of inheriting it" +``` + +--- + +### Task 4: Prove equivalence against `DynamicChunk` + +**Files:** +- Create: `falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoChunkEquivalenceTest.java` + +**Interfaces:** +- Consumes: `FalcoChunk` from Task 3. +- Produces: nothing. This task exists to make US-1.03 and NFR-004 true. + +**Model:** `falco-light/src/test/java/net/onelitefeather/falco/light/LightEngineEquivalenceTest.java` — fixed seed as a named constant, parameterised over arrangements, and an anti-tautology assertion that the fixture is not empty. + +- [ ] **Step 1: Write the test** + +```java +package net.onelitefeather.falco.instance; + +import net.minestom.server.MinecraftServer; +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.DynamicChunk; +import net.minestom.server.instance.Instance; +import net.minestom.server.instance.InstanceContainer; +import net.minestom.server.instance.block.Block; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; + +import java.util.Random; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; + +@DisplayName("A Falco chunk against the chunk of Minestom") +class FalcoChunkEquivalenceTest { + + private static final long SEED = 20260801L; + private static final int MIN_Y = -64; + private static final int HEIGHT = 384; + + private static Instance instance; + + @BeforeAll + static void server() { + if (MinecraftServer.process() == null) { + MinecraftServer.init(); + } + instance = MinecraftServer.getInstanceManager().createInstanceContainer(); + } + + private static void fill(Chunk chunk, int distinctStates, long seed) { + final Random random = new Random(seed); + final Block[] blocks = new Block[distinctStates]; + + for (int index = 0; index < distinctStates; index++) { + blocks[index] = Block.fromStateId(index + 1); + } + chunk.lockWriteLock(); + try { + for (int y = MIN_Y; y < MIN_Y + HEIGHT; y++) { + for (int z = 0; z < 16; z++) { + for (int x = 0; x < 16; x++) { + chunk.setBlock(x, y, z, blocks[random.nextInt(distinctStates)]); + } + } + } + } finally { + chunk.unlockWriteLock(); + } + } + + @ParameterizedTest(name = "{0} distinct states") + @ValueSource(ints = {1, 2, 16, 64, 256, 1024}) + @DisplayName("holds the same block at every position") + void testEveryPositionAgrees(int distinctStates) { + final Chunk minestom = new DynamicChunk(instance, 0, 0); + final Chunk falco = new FalcoChunk(instance, 0, 0); + + fill(minestom, distinctStates, SEED); + fill(falco, distinctStates, SEED); + + int nonAir = 0; + + minestom.lockReadLock(); + falco.lockReadLock(); + try { + for (int y = MIN_Y; y < MIN_Y + HEIGHT; y++) { + for (int z = 0; z < 16; z++) { + for (int x = 0; x < 16; x++) { + final Block expected = minestom.getBlock(x, y, z); + final Block actual = falco.getBlock(x, y, z); + + assertEquals(expected, actual, + "block at " + x + "/" + y + "/" + z + " with " + distinctStates + " states"); + if (!expected.isAir()) { + nonAir++; + } + } + } + } + } finally { + falco.unlockReadLock(); + minestom.unlockReadLock(); + } + assertTrue(nonAir > 0, "the fixture wrote nothing, so this run compared two empty chunks"); + } +} +``` + +- [ ] **Step 2: Run it** + +```bash +./gradlew :falco-instance:test --tests "*FalcoChunkEquivalenceTest*" +``` + +Expected: PASS for all six parameters. A failure names the exact position — that is the point of the message. + +- [ ] **Step 3: Commit** + +```bash +git add falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoChunkEquivalenceTest.java +git commit -m "test(instance): prove the bridge chunk agrees with DynamicChunk everywhere" +``` + +--- + +### Task 5: The chunk inside a plain `InstanceContainer` (US-1.05) + +**Files:** +- Create: `falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoChunkInContainerTest.java` + +**Interfaces:** +- Consumes: `FalcoChunk` from Task 3. +- Produces: nothing. This is the gate stage 4 depends on: a shared instance needs an `InstanceContainer` as its block owner, so the chunk has to work inside one. + +- [ ] **Step 1: Write the test** + +```java +package net.onelitefeather.falco.instance; + +import net.minestom.server.MinecraftServer; +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.InstanceContainer; +import net.minestom.server.instance.block.Block; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertInstanceOf; + +@DisplayName("A Falco chunk owned by a plain InstanceContainer") +class FalcoChunkInContainerTest { + + @BeforeAll + static void server() { + if (MinecraftServer.process() == null) { + MinecraftServer.init(); + } + } + + @Test + @DisplayName("is created by the container, survives a write and unloads cleanly") + void testContainerOwnsTheChunk() { + final InstanceContainer container = MinecraftServer.getInstanceManager().createInstanceContainer(); + + container.setChunkSupplier(FalcoChunk::new); + + final Chunk chunk = container.loadChunk(0, 0).join(); + + assertInstanceOf(FalcoChunk.class, chunk, "the container has to use the supplier it was given"); + + container.setBlock(0, 0, 0, Block.STONE); + assertEquals(Block.STONE, container.getBlock(0, 0, 0)); + + container.unloadChunk(chunk); + assertFalse(chunk.isLoaded(), "the container reaches the protected unload hook itself"); + + MinecraftServer.getInstanceManager().unregisterInstance(container); + } +} +``` + +- [ ] **Step 2: Run it** + +```bash +./gradlew :falco-instance:test --tests "*FalcoChunkInContainerTest*" +``` + +Expected: PASS. If `isLoaded()` stays true after `unloadChunk`, the container did not reach the hook — check whether `FalcoChunk` accidentally overrides `unload()` with a wider signature. + +- [ ] **Step 3: Commit** + +```bash +git add falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoChunkInContainerTest.java +git commit -m "test(instance): run the bridge chunk inside a plain InstanceContainer" +``` + +--- + +### Task 6: Measure that the bridge cost nothing + +**Files:** +- Modify: none. `falco-benchmarks` already carries `ChunkComparisonBenchmark` and `ChunkFootprintTest`, both comparing `FalcoChunk` against `DynamicChunk`. + +**This task is the acceptance gate of the whole stage.** Before the rewrite, `ChunkFootprintTest` reported `DELTA B = 0` across all fifteen fill variants and `ChunkComparisonBenchmark` reported `getBlock`, `setBlock` and `heightmapRefresh` as indistinguishable. Stage 1 changes the structure and must not change either. + +- [ ] **Step 1: Run the footprint test** + +```bash +./gradlew :falco-benchmarks:test --tests "*ChunkFootprintTest*" -i +``` + +Expected: **`DELTA B = 24` in every row, and exactly one object more** — the `SectionBlockStorage` itself. + +**Corrected after measuring.** This step first demanded `DELTA B = 0`, and that demand was wrong when it was written: an indirection is an object, so a chunk that *holds* its storage instead of *being* it must weigh one object more. Zero was never reachable while the storage is a separate type, and a separate type is the entire purpose of this stage. Measured on the pinned build: 192 → 193 objects, 6 848 → 6 872 B. + +The assertion is therefore **tightened, not relaxed**. It must require that the extra weight is exactly one object of class `SectionBlockStorage`; a second object, or 24 bytes belonging to any other class, still fails. That preserves what the equality check existed for — catching a field somebody adds behind the project's back. A tolerance such as "at most 64 bytes" would not, and is explicitly rejected. + +For scale: 24 B is 0.35 % of a fresh chunk and 0.01 % of a generated one, against the 2 911 B per chunk that stage 2 removes. + +- [ ] **Step 2: Run the comparison benchmark, scouting configuration** + +```bash +./gradlew :falco-benchmarks:jmh -Pjmh.quick \ + -Pjmh.include="ChunkComparisonBenchmark" \ + -Pjmh.params="distinctStates=1,64,1024;fillShape=RANDOM_RUNS" +``` + +Expected: `falcoGetBlock`, `falcoSetBlock` and `falcoHeightmapRefresh` within the error bars of their `minestom*` counterparts. Note that `minestomCopy`/`falcoCopy` are **not** comparable — they measure Minestom's viewer cache leak; use `minestomCopyIsolated`/`falcoCopyIsolated` instead. + +- [ ] **Step 3: Run the full test suite** + +```bash +./gradlew :falco-instance:test :falco-light:test :falco-anvil:test +``` + +Expected: all PASS. `falco-light` matters here because `FalcoLightingChunk` still extends `DynamicChunk` — stage 1 does not touch it, and it must keep working. + +- [ ] **Step 4: Record the result in the plan** + +Append a short section to this file under a heading `## Stage 1 result`, stating the measured delta and the date. If the delta is not zero, state the number and the suspected cause instead of rounding it away. + +- [ ] **Step 5: Commit** + +```bash +git add docs/superpowers/plans/2026-08-01-falco-block-storage.md +git commit -m "docs(plan): record what stage 1 measured" +``` + +--- + +## Definition of done + +- [ ] `BlockStorage` exists, with contract tests that stage 2's implementation will inherit unchanged +- [ ] `FalcoChunk` extends `Chunk` and holds its storage instead of inheriting it +- [ ] Equivalence against `DynamicChunk` is proven position by position over six state counts +- [ ] The chunk loads, is written to, and unloads inside a plain `InstanceContainer` +- [ ] `ChunkFootprintTest` reports `DELTA B = 24`, and its assertion requires that the extra object is a `SectionBlockStorage` rather than merely allowing 24 bytes from anywhere +- [ ] `falco-instance`, `falco-light` and `falco-anvil` tests all pass +- [ ] Every new public type carries `@ApiStatus.Experimental`, `@author`, `@version` and `@since 0.4.0` + +## What stage 1 deliberately does not do + +Named here so that a reviewer does not read them as omissions: no flyweight for empty sections, no lazy heightmaps, no packed flags, no `optimize()` after generation, no facade split of `FalcoInstance`, no shared instance. Those are stages 2 to 4. Stage 1 buys the seam they all need, and pays for it with a measurement that proves the seam is free. + +--- + +## Stage 1 result + +Measured on 2026-08-01, on the branch `feat/block-storage` at the commit that precedes this section, +against Minestom as pinned by the build and JDK 25.0.3 (Temurin). + +### The footprint, which is citable + +`./gradlew :falco-benchmarks:test --tests "*ChunkFootprintTest*" -i`, all three tests pass. Legacy +object headers of twelve bytes, eight byte alignment, sizes taken through the JOL instrumentation +agent (`falco.compactHeaders=false`), so every figure below is a number under that mode and must not +be quoted next to a number taken under `-XX:+UseCompactObjectHeaders`. + +| | objects | bytes | +| --- | --- | --- | +| `DynamicChunk`, fresh | 192 | 6 848 | +| `FalcoChunk`, fresh | 193 | 6 872 | +| difference | **+1** | **+24** | + +`DELTA B = 24` in all sixteen rows of the second table as well — every distinct state count from one +to a thousand and twenty-four, in all three arrangements, from a chunk of 6 848 bytes to one of +229 784. The delta does not grow with the chunk, because the seam is one object and not a per-section +or per-block cost. + +The one extra object is the `SectionBlockStorage`. That is asserted rather than assumed: the +comparison runs per class over the union of the classes either side retains and demands equality +everywhere except `net.onelitefeather.falco.instance.SectionBlockStorage`, of which the Falco side has +to hold exactly one and the Minestom side none, plus the requirement that the whole byte difference is +the size of that one object. The chunk class itself and the lambda classes the JVM generates from it +are compared as a single post, since `DynamicChunk` and `FalcoChunk` are different classes by +construction and the generated names are not stable between runs; their object count and their bytes +still have to match, which is what holds the shallow size of the chunk under assertion. + +Three injected defects were used to confirm the assertion still bites, each reverted afterwards: + +| injected into `FalcoChunk` | caught by | +| --- | --- | +| `private final Object probe = new Object();` | per class comparison, `1` object of `java.lang.Object` against `0` | +| `private final BlockStorage probe = new SectionBlockStorage(0, 0);` | `FalcoChunk has to hold exactly one BlockStorage, not 2` | +| `private final long probe = System.nanoTime();` | the chunk post weighing 104 bytes against 96 | + +The third is the interesting one: a primitive field adds no object at all, and the run showed that +adding a reference field does not necessarily change the shallow size either, because the eighty byte +`FalcoChunk` had padding to spare. The byte comparison of the chunk post is what catches that case, +and it is the reason the assertion is not merely a count. + +### The tests + +`./gradlew :falco-instance:test :falco-light:test :falco-anvil:test --rerun-tasks`: 48, 189 and 193 +tests, no failure, no error, nothing skipped. `falco-light` matters because `FalcoLightingChunk` still +extends `DynamicChunk` and was deliberately left alone by this stage. + +`./gradlew :falco-benchmarks:test --rerun-tasks`: 36 tests over six classes, no failure, no error, one +skipped — `EmptySectionCensusTest` needs a real Anvil world next to the repository and aborts its +assumption when there is none. + +The closing review of this stage added tests to `falco-instance`, which is why a run today reports 66 +there instead of 48; the other three counts are unchanged. What they cover: the section a height +belongs to, asserted through `BlockStorage#section(int)` rather than by reading back what was written, +because every case used to sit at `y = 0..3` where `- minSection` contributes a constant and could be +deleted with the whole file staying green; the biomes, which nothing read or wrote through the seam in +either direction; and a column outside the chunk, which is the contract stage 2's storage inherits. + +That run is the one that carries US-1.03 and it is named separately because it is easy to miss: the +benchmark module's `test` task is an ordinary test task under `check`, but the module's name suggests +JMH and nothing else. The equivalence it proves is the strongest on the branch. +`FalcoChunkEquivalenceTest` drives 18 fixtures — three fill shapes against six state counts — through +`MinestomChunks#assertSameBlocks`, which compares every one of the 16·16·16·`sectionCount` positions +**and both heightmaps of every column**, and each fixture additionally goes through a scattered write +batch, a full heightmap refresh on both sides and three copy comparisons. The criterion US-1.03 +spells out is exactly that, heightmaps included. + +`falco-instance`'s own `FalcoChunkEquivalenceTest` is deliberately not the evidence for US-1.03. It is +weaker by construction: one fill shape, no heightmap comparison, no copy, so it would stay green if +the two `refresh` calls were deleted from `FalcoChunk#setBlock`. It earns its place by needing nothing +but the module it lives in, which is what makes it run in the fast loop; the criterion is met in +`falco-benchmarks`. + +### The comparison benchmark, which is NOT citable + +`./gradlew :falco-benchmarks:jmh -Pjmh.quick -Pjmh.include="ChunkComparisonBenchmark" +-Pjmh.params="distinctStates=1,64,1024;fillShape=RANDOM_RUNS"`, average time in microseconds per +operation, ± the 99.9 % confidence interval. + +**The conditions disqualify every number here from being quoted.** The scouting configuration is one +fork, two warmup iterations and three measurement iterations of one second — enough to see whether +two curves lie on top of each other, far too little to state a difference. The machine was under +other load throughout: sixteen hardware threads on an AMD Ryzen 7 5800X, load average 4.7 at the +start of the run. These numbers answer "is there a regression large enough to see through the noise", +and nothing else. + +| benchmark | states | Minestom | Falco | +| --- | --- | --- | --- | +| `getBlock` | 1 | 24,482 ± 6,267 | 24,779 ± 0,910 | +| `getBlock` | 64 | 28,958 ± 9,285 | 29,688 ± 4,784 | +| `getBlock` | 1024 | 34,794 ± 4,800 | 34,682 ± 11,410 | +| `setBlock` | 1 | 68,489 ± 6,880 | 73,740 ± 9,023 | +| `setBlock` | 64 | 101,137 ± 2,771 | 105,127 ± 8,939 | +| `setBlock` | 1024 | 103,151 ± 34,972 | 103,009 ± 35,957 | +| `heightmapRefresh` | 1 | 6,448 ± 0,525 | 6,819 ± 0,833 | +| `heightmapRefresh` | 64 | 8,289 ± 0,697 | 8,101 ± 0,495 | +| `heightmapRefresh` | 1024 | 7,437 ± 1,585 | **76,423 ± 2147,865** | +| `copyIsolated` | 1 | 7,058 ± 3,348 | 6,607 ± 0,273 | +| `copyIsolated` | 64 | 12,957 ± 3,059 | 12,895 ± 3,495 | +| `copyIsolated` | 1024 | 20,520 ± 9,433 | 20,107 ± 6,239 | + +Every pair but one overlaps inside its error bars. `minestomCopy` and `falcoCopy` are omitted on +purpose: they measure Minestom's viewer cache leak along with the copy and are not comparable to +anything, which is why `copyIsolated` exists. + +The exception is `falcoHeightmapRefresh` at 1 024 states, and it is not a finding. Its three +iterations were 212,367, 8,737 and 8,164 µs/op — the second and third sit next to Minestom's 7,437, +the first is a stall of the loaded machine, and the resulting error bar of ± 2 147 µs is larger than +the mean by a factor of twenty-eight, which is JMH stating that the trial measured nothing. The two +warmup iterations of the same trial were 8,506 and 8,106. It has to be rerun on an idle machine +before anyone treats it as either a regression or its absence. + +### What this stage bought and what it cost + +The seam costs one object of 24 bytes per chunk: 0,35 % of a fresh chunk of 6 848 bytes, 0,01 % of a +generated one of roughly two hundred kibibytes, against the 2 911 bytes per chunk stage 2 is planned +to remove. Nothing in the time measurements survives its own error bars as a difference. The stage is +accepted with the delta stated rather than rounded to zero. diff --git a/docs/superpowers/plans/2026-08-02-falco-instance-facade.md b/docs/superpowers/plans/2026-08-02-falco-instance-facade.md new file mode 100644 index 0000000..7ea8bfc --- /dev/null +++ b/docs/superpowers/plans/2026-08-02-falco-instance-facade.md @@ -0,0 +1,4947 @@ +# Falco Instance Facade — Stage 3 Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Take `FalcoInstance` apart along the responsibilities it already has, so that the steps of a chunk's life become reachable one at a time; give a chunk more than one lifecycle extension, so that Falco's light and Falco's instance stop being mutually exclusive; and remove the one thing the unload path still leaves behind. + +**Architecture:** A facade over four parts. `FalcoInstance` keeps every method `Instance` demands and holds nothing but four references: `ChunkRegistry` (which chunk sits where, and which position is busy), `ChunkLifecycle` (create, generate, publish, unload, notify), `BlockWriter` (a block write and everything it wakes up) and `ChunkPersistence` (the loader and the four save paths). A fifth type, `ChunkGeneration`, is a collaborator of `ChunkLifecycle` rather than a part of the facade, because a chunk is generated exactly once and that once is inside its load. The extension point is `ChunkLifecycleListener`, installed on the chunk as a single nullable reference, composed with `ChunkLifecycleListener#of` when there is more than one, so that a chunk with no listener pays one field and no allocation. + +**Tech Stack:** Java 25, Gradle, JUnit 5, Cyano (Minestom test extension), JMH + JOL for measurement, fastutil, `com.sun.management.ThreadMXBean` for per-thread allocation counting. + +## Global Constraints + +Copied verbatim from the spec (`docs/superpowers/specs/2026-08-01-falco-instance-chunk-design.md`, §7): + +- **NFR-001** — The modules shall compile and run against the pinned Minestom version without reflection, `--add-opens` or an open module. +- **NFR-002** — The modules shall use only language and JDK features that are final in Java 25; no preview and no incubator feature shall be required to build or run. +- **NFR-003** — If a performance claim is published, then shall a JMH or JOL measurement in this repository support it, stated with its conditions. +- **NFR-004** — While a comparison benchmark runs, shall it fail rather than report a number if the two sides disagree on their result. +- **NFR-005** — When a chunk read fails, shall the failure reach the caller instead of being reported as an absent chunk. +- **NFR-006** — While a block is written, shall the lock held be the lock of the chunk it touches, not a monitor over the instance. +- **NFR-007** — The chunk shall allocate no object per block read on any path. +- **NFR-008** — The chunk shall not require `-XX:+UseCompactObjectHeaders`; where the flag helps, the gain shall be stated per class and measured, never as a percentage. +- **NFR-009** — Every new public type shall carry `@ApiStatus.Experimental` while the module is experimental. + +Repository conventions, non-negotiable: + +- **Source and Javadoc are English**, and Javadoc *justifies* decisions in `

` paragraphs and `

` sections. Every type carries `@author TheMeinerLP`, `@version`, `@since`. **Changing an existing class raises its `@version`.** Model: `falco-light/src/main/java/net/onelitefeather/falco/light/ChunkLightService.java`. +- **Javadoc runs with `-Werror`** (`build.gradle.kts:35-37`). Every public and protected member of every new type needs a complete comment with `@param`, `@return` and `@throws`, or the build fails. +- **Gradle files stay comment-free.** +- **Minestom reference is the pinned sources jar**, unpacked at `/tmp/claude-1000/-mnt-projects-oss-onelitefeather-Falco/34edb948-9dfe-4540-9666-9e29f0d44d7b/scratchpad/minestom-src/`. The clone at `/mnt/projects/oss/minestom/Minestom` is ten months stale and must not be used. +- Work happens in the worktree `/mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage`, on branch `feat/block-storage`. Every Gradle command is prefixed with `cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage &&`, because the working directory of a shell call does not persist. +- **Measured, not asserted.** No figure without its conditions, no green test that claims instead of checking. Every new assertion in this plan comes with a named injected defect that has to make it red. + +## The starting point + +From the `## Stage 2 result` section of `docs/superpowers/plans/2026-08-02-falco-lazy-sections.md`, measured 2026-08-02, legacy object headers of twelve bytes, JOL through the instrumentation agent, JDK 25.0.3 (Temurin). + +| # | What | Figure | +|---|---|---| +| T1 | A fresh `FalcoChunk` | **25 objects, 840 B**, against 192 / 6 848 for `DynamicChunk` | +| T2 | A filled chunk | 104 B saved, at every state count and every arrangement | +| T3 | What a chunk costs inside the instance it was built for | **161 B** for a `FalcoInstance`, 185 B for an `InstanceContainer` | +| T4 | Test counts, all green | `:falco-instance:` 143, `:falco-anvil:` 193, `:falco-light:` 189, `:falco-demo:` 139, `:falco-benchmarks:` 38 | +| T5 | `FalcoInstance.java` | **1 272 lines**, `@version 1.2.0` | +| T6 | Viewer cache growth, `InstanceContainer` | 1 entry per chunk **construction**, linear, never removed | +| T7 | Viewer cache growth, `FalcoInstance` | 1 entry per chunk **position**, never removed | + +T3 is the figure this stage moves. T1 and T2 are the figures this stage must not move by accident: `ChunkFootprintTest` asserts a declared per-class difference table and the equality of the two chunks' shallow sizes, and Task 8 adds a field to `FalcoChunk`. That is not a reason to loosen the assertion; it is a reason to re-measure and re-declare it. + +## What the net covers, and what it does not + +A refactoring of working code is only as safe as the tests that ran before it. This is the inventory, taken by reading every test of `falco-instance` rather than by trusting the file names. + +**What the net already holds.** + +| Test | What it pins | +|---|---| +| `FalcoInstanceTest` (14) | registration, `loadChunk` twice giving one chunk, `getChunk` before a load, `setBlock` read back, auto chunk load on and off, the server ticking the instance, a foreign chunk supplier being refused, a player becoming a viewer, the void depth | +| `FalcoInstanceUnloadTest` (6) | `unloadChunk` clearing the flag and the map, the unload event firing once, `unregister` unloading everything, the unregister event still firing, unregistering twice, and the Minestom behaviour that makes the class necessary | +| `FalcoInstanceLoadRaceTest` (3) | unregister during a running load, an unregister racing every running load, and a thousand concurrent loads and unloads never leaving a chunk that cannot be unloaded | +| `FalcoInstanceGeneratorTest` (12) | the generator being handed back, a generated chunk carrying its blocks, the loader winning over the generator, a special block surviving generation, a throwing generator failing the load, a throwing generator leaving a loaded chunk alone, `generateChunk` on a loaded chunk, forks into loaded and unloaded chunks, the heightmap covering the whole chunk, an empty world without a generator | +| `FalcoChunkTest` (11) | the load and unload hooks, the copy, the heightmaps built on demand and built once, the tickable counter from five directions | +| `SectionMaterialisationTest`, `LazySectionBlockStorageTest`, `BlockStorageTest`, `PaletteCompactionTest` | everything below the chunk | + +**What the net does not hold, verified by grep over `falco-instance/src/test` and `falco-demo/src`.** + +- `placeBlock` — **no test anywhere.** Not one call site in any test of the repository. +- `breakBlock` — **no test anywhere.** Neither the event, nor the air case that resends the chunk, nor the particle packet, nor the exclusion of the breaking player. +- `updateNeighbours` and `placementState` — **no test anywhere.** No placement rule is installed by any test, so the entire branch under `doBlockUpdates` has never run. +- The recursion guard `currentlyChangingBlocks` and its clearing in `tick` — **no test.** +- `getLastBlockChangeTime` / `refreshLastBlockChangeTime` — **no test.** +- `saveInstance`, `saveChunkToStorage`, `saveChunksToStorage` and `runSave` — **no test on `FalcoInstance`.** `TimingChunkLoaderTest` in `falco-demo` exercises a loader, not the instance's four save entry points, and neither the parallel nor the failing branch of `runSave` has ever been executed. +- `setChunkLoader` / `getChunkLoader` — **no test.** + +Every one of those is code Task 6 and Task 3 move to another class. **Task 1 writes that net before anything moves**, and it is the first task for exactly that reason: a refactoring justified by testability that begins by moving untested code is the same mistake in a better outfit. + +## Five traps, verified against the sources before they were written down + +**The facade will re-accumulate state unless something forbids it.** §4.3 of the spec says so in as many words, and §8 lists it as the open question of this stage. A delegation layer with three fields of its own is the class it replaced with extra indirection. Task 7 answers it with a test over `FalcoInstance.class.getDeclaredFields()`: every non-static declared field has to be `final` and of one of the four part types, and there have to be exactly four. That is reflection in a test, which the module rule does not cover and which this repository already does deliberately in `JolMeasurement` — with the same property, that it fails loudly rather than silently degrading. + +**The viewer cache entry cannot be removed through public API.** `EntityTracker#viewable(List, int, int)` is the only public door and it is `computeIfAbsent`; there is no counterpart. The map is `EntityTrackerImpl.TargetEntry#viewers` (`EntityTrackerImpl.java:269`), the key is the package-private record `ChunkViewKey` (`:252`) and `EntityTrackerImpl` itself is `final class` with no modifier (`:31`). All three are reachable from a class **in the package `net.minestom.server.instance`**, which is how `ChunkViewerCacheLeakTest` reads the map today without reflection. Task 9 puts one such class into `falco-instance/src/main/java`. The price is a split package with Minestom, which is invisible on the classpath and fatal on the module path; Falco has no `module-info.java` and neither does any of its consumers today, and Task 9 states the restriction in the class comment rather than discovering it later. + +**`ChunkView` is `private`, so the removal must not name it.** `EntityTrackerImpl.ChunkView` is declared `private final class` (`:289`), so a class in the same package may use the expression `entry.viewers` but may not write down the type of what `Map#remove` returns. `entry.viewers.keySet().remove(key)` returns a `boolean` and never mentions it. `entry.viewers.remove(key) != null` may or may not compile depending on how javac treats the inaccessible type argument, and is not worth finding out. + +**A lifecycle event built before the listener check costs an allocation on every transition of every chunk.** With 4 096 chunks at twenty ticks a second, one 24-byte record per chunk per tick is 2 MB/s of garbage for a server that registered no listener at all. US-3.04 forbids it and Task 8 measures it with `com.sun.management.ThreadMXBean#getCurrentThreadAllocatedBytes`, in both arms, with the listener arm publishing the event to a static field so that escape analysis cannot delete the allocation the measurement is looking for. A test that only measures the null arm would pass against an implementation that allocates nothing because the JIT removed it, which is the failure class this project has been hit by six times. + +**`Heightmap`, `getSections()` and `getSection(int)` materialise.** Unchanged from stage 2 and repeated here because this stage writes new tests that walk chunks: to read what a chunk currently holds, use `BlockStorage#view(int)`, `#views()`, `#shared(int)` and `#materialisedSections()`. A test that reaches for `getSections()` to check something unrelated silently materialises twenty-four sections and invalidates every count around it. + +## File Structure + +| File | Responsibility | +|---|---| +| `falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkRegistry.java` | **Create.** Which chunk sits at which index, and which position is busy. Owns the two maps and every atomic transition of a position. | +| `.../instance/ChunkLifecycle.java` | **Create.** Create, generate, load, publish, unload, notify. Owns the chunk supplier and the listener. | +| `.../instance/ChunkGeneration.java` | **Create.** The generator, the pending forks and the commit. A collaborator of `ChunkLifecycle`, not a part of the facade. | +| `.../instance/BlockWriter.java` | **Create.** `setBlock`, `placeBlock`, `breakBlock`, the neighbour updates, the recursion guard and the last change time. | +| `.../instance/ChunkPersistence.java` | **Create.** The chunk loader and the four save paths. | +| `.../instance/ChunkLifecycleListener.java` | **Create.** The extension point: `onLoad`, `onPublish`, `onTick`, `onUnload`, `onBlockChange`, plus `of` for composition. | +| `.../instance/ChunkLifecycleEvent.java` | **Create.** The record the four transitions hand out, built only when a listener exists. | +| `.../instance/FalcoInstance.java` | **Rewrite.** Four fields, no logic. `@version 1.2.0` → `2.0.0`. | +| `.../instance/FalcoChunk.java` | **Modify.** One nullable listener reference, notified on load, publish, tick, unload and block change. `@version 3.4.1` → `3.5.0`. | +| `falco-instance/src/main/java/net/minestom/server/instance/ChunkViewerCache.java` | **Create.** The one door to the viewer cache Minestom does not open. Split package, on purpose, documented. | +| `falco-instance/src/test/java/.../instance/FalcoInstanceBlockWriteTest.java` | **Create.** The net for `placeBlock`, `breakBlock`, the neighbour updates and the recursion guard, written before any of it moves. | +| `falco-instance/src/test/java/.../instance/FalcoInstancePersistenceTest.java` | **Create.** The net for the four save paths, both branches of `runSave` and the loader swap. | +| `falco-instance/src/test/java/.../instance/ChunkRegistryTest.java` | **Create.** The transitions of a position, driven directly. | +| `falco-instance/src/test/java/.../instance/ChunkLifecycleTest.java` | **Create.** US-3.02: publish and complete a load without driving a full load. | +| `falco-instance/src/test/java/.../instance/ChunkGenerationTest.java` | **Create.** The fork map, driven directly. | +| `falco-instance/src/test/java/.../instance/BlockWriterTest.java` | **Create.** The writer, driven directly. | +| `falco-instance/src/test/java/.../instance/InstanceFacadeTest.java` | **Create.** The facade holds four final fields and nothing else. | +| `falco-instance/src/test/java/.../instance/ChunkLifecycleListenerTest.java` | **Create.** US-3.03: two listeners, every transition, both notified. | +| `falco-instance/src/test/java/.../instance/ChunkLifecycleAllocationTest.java` | **Create.** US-3.04: no listener, no allocation — counted, in both arms. | +| `falco-instance/src/test/java/net/minestom/server/instance/ChunkViewerCacheTest.java` | **Create.** US-3.01: a load/unload cycle leaves the cache where it found it. | +| `falco-light/src/main/java/.../light/FalcoLightingChunk.java` | **Rewrite.** `extends FalcoChunk`, holding the light packet cache and installing `ChunkLightListener`. `@version 1.0.0` → `2.0.0`. | +| `falco-light/src/main/java/.../light/ChunkLightListener.java` | **Create.** The four reports light needs, as a `ChunkLifecycleListener`. | +| `falco-light/build.gradle.kts` | **Modify.** `compileOnly(project(":falco-instance"))` and `testImplementation(project(":falco-instance"))`. | +| `falco-demo/src/main/java/.../demo/ServerStack.java` | **Modify.** The note that says the two cannot be combined stops being true. `@version 1.0.0` → `2.0.0`. | +| `falco-benchmarks/src/test/java/net/minestom/server/instance/ChunkViewerCacheLeakTest.java` | **Modify.** Gains the load/unload cycle. `@version 1.0.1` → `1.1.0`. | +| `falco-benchmarks/src/jmh/java/.../benchmark/instance/ChunkLookupBenchmark.java` | **Create.** What a chunk lookup costs and allocates, boxed against unboxed. | +| `settings.gradle.kts`, `falco-instance/build.gradle.kts` | **Modify.** `flare-fastutil` as a `compileOnly` dependency for the primitive chunk index. | + +Already in the repository and **not to be reinvented**: `ChunkViewerCacheLeakTest` (the door into the viewer cache without reflection), `ChunkFootprintTest` (the per-class difference table and the shallow-size equality), `SectionMaterialisationTest` (how to count something instead of timing it), `FalcoChunkEquivalenceTest` in `falco-benchmarks` (the evidence for US-1.03). All of them must be re-run at the end of the stage. + +--- + +### Task 1: The net, before anything moves + +**Files:** +- Create: `falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoInstanceBlockWriteTest.java` +- Create: `falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoInstancePersistenceTest.java` + +**Interfaces:** +- Consumes: `FalcoInstance` as stage 2 left it — `setBlock(int,int,int,Block,boolean)`, `placeBlock(BlockHandler.Placement,boolean)`, `breakBlock(Player,Point,BlockFace,boolean)`, `getLastBlockChangeTime()`, `refreshLastBlockChangeTime()`, `saveInstance()`, `saveChunkToStorage(Chunk)`, `saveChunksToStorage()`, `setChunkLoader(ChunkLoader)`, `getChunkLoader()`. +- Produces: nothing. This task adds no production code at all, and that is the point. + +**Why this is the first task.** Tasks 3 and 6 move `placeBlock`, `breakBlock`, `updateNeighbours`, the recursion guard and all four save paths into new classes. Not one of those has a test today — see the inventory above, which was taken by grep and not by guessing. A move of untested code cannot be verified by running the suite, because the suite says nothing about it either way. + +- [ ] **Step 1: Write the block write net** + +Create `FalcoInstanceBlockWriteTest.java`. A placement rule is registered so the neighbour update branch runs; without one, `updateNeighbours` returns on its first `rule == null`. + +```java +package net.onelitefeather.falco.instance; + +import net.minestom.server.MinecraftServer; +import net.minestom.server.coordinate.BlockVec; +import net.minestom.server.coordinate.Vec; +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.block.Block; +import net.minestom.server.instance.block.BlockFace; +import net.minestom.server.instance.block.BlockHandler; +import net.minestom.server.instance.block.rule.BlockPlacementRule; +import net.minestom.server.world.DimensionType; +import net.minestom.testing.Env; +import net.minestom.testing.extension.MicrotusExtension; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; + +import java.util.UUID; +import java.util.concurrent.atomic.AtomicInteger; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNotEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Pins what a block write through {@link FalcoInstance} does, before the code that does it moves. + *

+ * Every case here covers a path that had no test at all when this class was written: the placement + * entry point, the break entry point, the neighbour update that follows a write, the recursion guard + * that keeps a handler from destroying its own block forever, and the change timestamp. The plan of + * stage 3 moves all of them into {@code BlockWriter}, and a move can only be checked against + * behaviour somebody wrote down first. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ExtendWith(MicrotusExtension.class) +@DisplayName("A block write through a Falco instance") +class FalcoInstanceBlockWriteTest { + + /** + * The height every case writes at, well inside the overworld and away from both limits. + */ + private static final int Y = 64; + + /** + * Creates a registered instance in the environment of the test. + * + * @param env the environment which provides the server process + * @return the registered instance + */ + private static FalcoInstance registered(Env env) { + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + return instance; + } + + @Test + @DisplayName("places a block through placeBlock and reports that it did") + void testPlaceBlockWritesTheBlock(Env env) { + final FalcoInstance instance = registered(env); + instance.loadChunk(0, 0).join(); + + final boolean placed = instance.placeBlock(new BlockHandler.Placement(Block.STONE, Block.AIR, + instance, new BlockVec(1, Y, 1)), true); + + assertTrue(placed, "a loaded chunk accepts a placement"); + assertEquals(Block.STONE, instance.getBlock(1, Y, 1)); + } + + @Test + @DisplayName("refuses a placement into a chunk which is not loaded") + void testPlaceBlockRefusesAnUnloadedChunk(Env env) { + final FalcoInstance instance = registered(env); + + final boolean placed = instance.placeBlock(new BlockHandler.Placement(Block.STONE, Block.AIR, + instance, new BlockVec(1, Y, 1)), true); + + assertFalse(placed, "there is no chunk at that position, so nothing can be placed"); + } + + @Test + @DisplayName("breaks a block, replaces it with what the event decided and tells the viewers") + void testBreakBlockReplacesTheBlock(Env env) { + final FalcoInstance instance = registered(env); + instance.loadChunk(0, 0).join(); + instance.setBlock(1, Y, 1, Block.STONE); + final var connection = env.createConnection(); + final var player = connection.connect(instance, new Vec(0, Y, 0)); + + final boolean broken = instance.breakBlock(player, new BlockVec(1, Y, 1), BlockFace.TOP, true); + + assertTrue(broken, "a solid block in a loaded chunk can be broken"); + assertEquals(Block.AIR, instance.getBlock(1, Y, 1)); + } + + @Test + @DisplayName("refuses to break air and does not pretend it broke something") + void testBreakBlockRefusesAir(Env env) { + final FalcoInstance instance = registered(env); + instance.loadChunk(0, 0).join(); + final var connection = env.createConnection(); + final var player = connection.connect(instance, new Vec(0, Y, 0)); + + assertFalse(instance.breakBlock(player, new BlockVec(1, Y, 1), BlockFace.TOP, true), + "there is no block there, so the client is resent the chunk instead"); + } + + @Test + @DisplayName("lets a placement rule reshape the neighbour of a written block") + void testANeighbourReshapesItself(Env env) { + final FalcoInstance instance = registered(env); + instance.loadChunk(0, 0).join(); + final AtomicInteger updates = new AtomicInteger(); + MinecraftServer.getBlockManager().registerBlockPlacementRule(new BlockPlacementRule(Block.GLASS) { + + @Override + public Block blockUpdate(UpdateState state) { + updates.incrementAndGet(); + return Block.GLOWSTONE; + } + + @Override + public Block blockPlace(PlacementState state) { + return state.block(); + } + }); + instance.setBlock(2, Y, 1, Block.GLASS); + + instance.setBlock(1, Y, 1, Block.STONE, true); + + assertTrue(updates.get() > 0, "the neighbour of the written block has to be asked to reshape itself"); + assertEquals(Block.GLOWSTONE, instance.getBlock(2, Y, 1), + "what the rule returned has to end up in the chunk"); + } + + @Test + @DisplayName("does not run neighbour updates when the caller switched them off") + void testNeighbourUpdatesCanBeSwitchedOff(Env env) { + final FalcoInstance instance = registered(env); + instance.loadChunk(0, 0).join(); + final AtomicInteger updates = new AtomicInteger(); + MinecraftServer.getBlockManager().registerBlockPlacementRule(new BlockPlacementRule(Block.OAK_LEAVES) { + + @Override + public Block blockUpdate(UpdateState state) { + updates.incrementAndGet(); + return state.currentBlock(); + } + + @Override + public Block blockPlace(PlacementState state) { + return state.block(); + } + }); + instance.setBlock(4, Y, 1, Block.OAK_LEAVES); + + instance.setBlock(3, Y, 1, Block.STONE, false); + + assertEquals(0, updates.get(), "doBlockUpdates=false has to skip the neighbour pass entirely"); + } + + @Test + @DisplayName("stops a handler which writes its own block again from recursing") + void testTheRecursionGuardHolds(Env env) { + final FalcoInstance instance = registered(env); + instance.loadChunk(0, 0).join(); + final AtomicInteger writes = new AtomicInteger(); + final Block looping = Block.STONE.withHandler(new BlockHandler() { + + @Override + public void onPlace(Placement placement) { + writes.incrementAndGet(); + instance.setBlock(placement.getBlockPosition(), placement.getBlock()); + } + + @Override + public net.kyori.adventure.key.Key getKey() { + return net.kyori.adventure.key.Key.key("falco", "looping"); + } + }); + + instance.setBlock(5, Y, 5, looping); + + assertEquals(1, writes.get(), + "the second write of the same block to the same position has to be dropped by the guard"); + } + + @Test + @DisplayName("lets the same block be written again after the tick which cleared the guard") + void testTheGuardIsClearedByATick(Env env) { + final FalcoInstance instance = registered(env); + instance.loadChunk(0, 0).join(); + instance.setBlock(6, Y, 6, Block.STONE); + + instance.tick(System.currentTimeMillis()); + instance.setBlock(6, Y, 6, Block.DIRT); + instance.tick(System.currentTimeMillis()); + instance.setBlock(6, Y, 6, Block.STONE); + + assertEquals(Block.STONE, instance.getBlock(6, Y, 6), + "the guard is scoped to one tick, so the same block can be written again afterwards"); + } + + @Test + @DisplayName("moves the last change time when a block is written") + void testTheChangeTimeMoves(Env env) { + final FalcoInstance instance = registered(env); + instance.loadChunk(0, 0).join(); + final long before = instance.getLastBlockChangeTime(); + + instance.setBlock(7, Y, 7, Block.STONE); + + assertNotEquals(before, instance.getLastBlockChangeTime(), + "a block write has to move the timestamp the batches read"); + } + + @Test + @DisplayName("loads the chunk a write lands in when auto chunk load is on") + void testAWriteLoadsItsChunk(Env env) { + final FalcoInstance instance = registered(env); + + instance.setBlock(600, Y, 600, Block.STONE); + + final Chunk chunk = instance.getChunkAt(600, 600); + assertTrue(chunk != null && chunk.isLoaded(), "the write has to have brought its chunk into the world"); + assertEquals(Block.STONE, instance.getBlock(600, Y, 600)); + } +} +``` + +- [ ] **Step 2: Run it and watch it pass** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +./gradlew :falco-instance:test --tests "*FalcoInstanceBlockWriteTest*" +``` + +Expected: **PASS, all ten.** This is a net, not a red-green cycle: the behaviour exists and is being written down. A failure here means the behaviour is not what this plan assumed, and the plan is wrong rather than the code — stop and re-read `FalcoInstance#writeBlock:413` before changing anything. + +- [ ] **Step 3: Prove the net bites** + +Comment out the line `if (Objects.equals(this.currentlyChangingBlocks.get(blockPosition), block)) return;` in `FalcoInstance:425`, run the test again, and see `testTheRecursionGuardHolds` fail with a `StackOverflowError` or a count above one. Restore the line. Then comment out `if (doBlockUpdates) updateNeighbours(blockPosition, updateDistance);` in `:443` and see `testANeighbourReshapesItself` fail. Restore it. A net that stays green while the thing it covers is deleted is not a net. + +- [ ] **Step 4: Write the persistence net** + +Create `FalcoInstancePersistenceTest.java`. Both branches of `runSave` have to run, and the failing branch of each has to reach the caller rather than a log. + +```java +package net.onelitefeather.falco.instance; + +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.ChunkLoader; +import net.minestom.server.instance.Instance; +import net.minestom.server.world.DimensionType; +import net.minestom.testing.Env; +import net.minestom.testing.extension.MicrotusExtension; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; + +import java.util.Collection; +import java.util.UUID; +import java.util.concurrent.CompletionException; +import java.util.concurrent.atomic.AtomicInteger; +import java.util.concurrent.atomic.AtomicReference; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Pins what the four save entry points of {@link FalcoInstance} do, before the code that does it + * moves into {@code ChunkPersistence}. + *

+ * None of them had a test when this class was written, and the branch that matters most had never + * been executed at all: a loader which saves in parallel takes a different path through + * {@code runSave} than one which does not, and a failure on either path has to reach the future the + * caller holds rather than the exception manager of the server. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ExtendWith(MicrotusExtension.class) +@DisplayName("The save paths of a Falco instance") +class FalcoInstancePersistenceTest { + + /** + * A loader which counts what it was asked to save and can be told to throw. + */ + private static final class CountingLoader implements ChunkLoader { + + /** + * Whether this loader claims to support saving off the calling thread. + */ + private final boolean parallel; + + /** + * What every save call throws, null for a loader which succeeds. + */ + private final RuntimeException failure; + + /** + * How often an instance save reached this loader. + */ + private final AtomicInteger instanceSaves = new AtomicInteger(); + + /** + * How often a chunk save reached this loader. + */ + private final AtomicInteger chunkSaves = new AtomicInteger(); + + /** + * The thread the last save ran on. + */ + private final AtomicReference lastThread = new AtomicReference<>(); + + /** + * Creates a loader. + * + * @param parallel whether it claims parallel saving + * @param failure what every save throws, null for none + */ + private CountingLoader(boolean parallel, RuntimeException failure) { + this.parallel = parallel; + this.failure = failure; + } + + @Override + public boolean supportsParallelSaving() { + return this.parallel; + } + + @Override + public void saveInstance(Instance instance) { + this.lastThread.set(Thread.currentThread()); + this.instanceSaves.incrementAndGet(); + if (this.failure != null) throw this.failure; + } + + @Override + public void saveChunk(Chunk chunk) { + this.lastThread.set(Thread.currentThread()); + this.chunkSaves.incrementAndGet(); + if (this.failure != null) throw this.failure; + } + + @Override + public void saveChunks(Collection chunks) { + this.lastThread.set(Thread.currentThread()); + this.chunkSaves.addAndGet(chunks.size()); + if (this.failure != null) throw this.failure; + } + } + + /** + * Creates a registered instance with the given loader. + * + * @param env the environment which provides the server process + * @param loader the loader of the instance + * @return the registered instance + */ + private static FalcoInstance registered(Env env, ChunkLoader loader) { + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD, loader); + env.process().instance().registerInstance(instance); + return instance; + } + + @Test + @DisplayName("saves the instance on the calling thread when the loader is not parallel") + void testSaveInstanceOnTheCallingThread(Env env) { + final CountingLoader loader = new CountingLoader(false, null); + final FalcoInstance instance = registered(env, loader); + + instance.saveInstance().join(); + + assertEquals(1, loader.instanceSaves.get()); + assertSame(Thread.currentThread(), loader.lastThread.get(), + "a loader without parallel support must not be moved off the calling thread"); + } + + @Test + @DisplayName("saves the instance off the calling thread when the loader is parallel") + void testSaveInstanceOnAVirtualThread(Env env) { + final CountingLoader loader = new CountingLoader(true, null); + final FalcoInstance instance = registered(env, loader); + + instance.saveInstance().join(); + + assertEquals(1, loader.instanceSaves.get()); + assertTrue(loader.lastThread.get().isVirtual(), + "a loader with parallel support has to be run on a virtual thread"); + } + + @Test + @DisplayName("hands a failing save back to the caller instead of swallowing it") + void testAFailingSaveReachesTheCaller(Env env) { + final RuntimeException boom = new IllegalStateException("the disk is on fire"); + final FalcoInstance instance = registered(env, new CountingLoader(false, boom)); + + final CompletionException thrown = assertThrows(CompletionException.class, + () -> instance.saveInstance().join()); + + assertSame(boom, thrown.getCause(), "the failure of the loader is the failure of the future"); + } + + @Test + @DisplayName("hands a failing parallel save back to the caller as well") + void testAFailingParallelSaveReachesTheCaller(Env env) { + final RuntimeException boom = new IllegalStateException("the disk is still on fire"); + final FalcoInstance instance = registered(env, new CountingLoader(true, boom)); + + final CompletionException thrown = assertThrows(CompletionException.class, + () -> instance.saveInstance().join()); + + assertSame(boom, thrown.getCause(), "moving the work to a virtual thread must not lose the failure"); + } + + @Test + @DisplayName("saves one chunk and every chunk through the loader") + void testChunkSaves(Env env) { + final CountingLoader loader = new CountingLoader(false, null); + final FalcoInstance instance = registered(env, loader); + final Chunk chunk = instance.loadChunk(0, 0).join(); + instance.loadChunk(1, 0).join(); + + instance.saveChunkToStorage(chunk).join(); + assertEquals(1, loader.chunkSaves.get()); + + instance.saveChunksToStorage().join(); + assertEquals(3, loader.chunkSaves.get(), "the second call has to hand over both loaded chunks"); + } + + @Test + @DisplayName("keeps the chunks it already has when the loader is swapped") + void testSwappingTheLoader(Env env) { + final CountingLoader first = new CountingLoader(false, null); + final CountingLoader second = new CountingLoader(false, null); + final FalcoInstance instance = registered(env, first); + final Chunk chunk = instance.loadChunk(0, 0).join(); + + instance.setChunkLoader(second); + + assertSame(second, instance.getChunkLoader()); + assertSame(chunk, instance.getChunk(0, 0), "swapping the loader must not touch loaded chunks"); + instance.saveChunkToStorage(chunk).join(); + assertEquals(0, first.chunkSaves.get(), "the old loader must not see the save"); + assertEquals(1, second.chunkSaves.get(), "the new loader has to"); + } +} +``` + +- [ ] **Step 5: Run it and watch it pass** + +```bash +./gradlew :falco-instance:test --tests "*FalcoInstancePersistenceTest*" +``` + +Expected: **PASS, all six.** + +- [ ] **Step 6: Prove this net bites too** + +Change `runSave` in `FalcoInstance:781` so its `catch (Throwable throwable)` returns `CompletableFuture.completedFuture(null)` instead of a failed future, and see both failure cases go red. Restore it. + +- [ ] **Step 7: Commit** + +```bash +git add falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoInstanceBlockWriteTest.java \ + falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoInstancePersistenceTest.java +git commit -m "test(instance): pin the block write and the save paths before they move" +``` + +--- + +### Task 2: `ChunkRegistry` + +**Files:** +- Create: `falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkRegistry.java` +- Modify: `falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoInstance.java` +- Test: `falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkRegistryTest.java` + +**Interfaces:** +- Consumes: nothing of Falco's. `CoordConversion#chunkIndex(int,int)` from Minestom. +- Produces: + - `ChunkRegistry()` + - `@Nullable Chunk chunk(long index)` + - `@Nullable Chunk chunk(int chunkX, int chunkZ)` + - `Collection chunks()` + - `List snapshot()` + - `List loadingPositions()` + - `int size()` + - `int loading()` + - `boolean idle()` + - `ChunkRegistry.LoadSlot acquire(long index, CompletableFuture own)` + - `void release(long index, CompletableFuture own)` + - `@Nullable CompletableFuture discard(long index)` + - `boolean publish(long index, FalcoChunk chunk, CompletableFuture future, Consumer insideLock)` + - `boolean remove(long index, FalcoChunk chunk, Consumer insideLock)` + - `sealed interface LoadSlot` with `record Loaded(Chunk chunk)`, `record Running(CompletableFuture future)`, `record Claimed(CompletableFuture future)` + + Tasks 5, 9 and 11 depend on exactly these names. + +**Reference:** `FalcoInstance#retrieveChunk:544` (the acquire), `#publishChunk:638` (the publish), `#unloadChunk:722` (the remove), `#discardRunningLoad:325` (the discard). The `compute` on `loadingChunks` is the lock of a position and its exact shape is load-bearing — `FalcoInstanceLoadRaceTest` exists because of it. Move it; do not rewrite it. + +- [ ] **Step 1: Write the failing test** + +```java +package net.onelitefeather.falco.instance; + +import net.minestom.server.coordinate.CoordConversion; +import net.minestom.server.instance.Chunk; +import net.minestom.server.world.DimensionType; +import net.minestom.testing.Env; +import net.minestom.testing.extension.MicrotusExtension; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; + +import java.util.UUID; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.atomic.AtomicInteger; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertInstanceOf; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Drives every transition of a chunk position directly, without a loader and without a load. + *

+ * This is half of US-3.02. The transitions used to be three {@code private} methods of a class of + * 1 272 lines and could only be reached by loading a chunk through a loader, which meant that a test + * of the publish had to be a test of the whole load path and could never cover the case where a + * publish is refused — that case needs an unload to interleave with a load, which is exactly what a + * full load path makes impossible to arrange. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ExtendWith(MicrotusExtension.class) +@DisplayName("The registry of chunk positions") +class ChunkRegistryTest { + + /** + * The position every case works on. + */ + private static final long INDEX = CoordConversion.chunkIndex(0, 0); + + /** + * Creates a registered instance to build chunks for. + * + * @param env the environment which provides the server process + * @return the registered instance + */ + private static FalcoInstance registered(Env env) { + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + return instance; + } + + @Test + @DisplayName("hands the first caller the slot and every later one the same future") + void testTheFirstCallerOwnsTheSlot(Env env) { + registered(env); + final ChunkRegistry registry = new ChunkRegistry(); + final CompletableFuture first = new CompletableFuture<>(); + final CompletableFuture second = new CompletableFuture<>(); + + assertInstanceOf(ChunkRegistry.LoadSlot.Claimed.class, registry.acquire(INDEX, first)); + final ChunkRegistry.LoadSlot slot = registry.acquire(INDEX, second); + + assertSame(first, assertInstanceOf(ChunkRegistry.LoadSlot.Running.class, slot).future(), + "the second caller has to receive the future of the first, not one of its own"); + } + + @Test + @DisplayName("hands back the published chunk instead of a slot") + void testAPublishedChunkEndsTheLoad(Env env) { + final FalcoInstance instance = registered(env); + final ChunkRegistry registry = new ChunkRegistry(); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + final CompletableFuture own = new CompletableFuture<>(); + registry.acquire(INDEX, own); + final AtomicInteger insideLock = new AtomicInteger(); + + assertTrue(registry.publish(INDEX, chunk, own, published -> insideLock.incrementAndGet())); + + assertEquals(1, insideLock.get(), "the step handed in has to run exactly once, while the position is held"); + assertSame(chunk, registry.chunk(INDEX)); + assertEquals(0, registry.loading(), "a published chunk releases the slot of its position"); + assertSame(chunk, assertInstanceOf(ChunkRegistry.LoadSlot.Loaded.class, + registry.acquire(INDEX, new CompletableFuture<>())).chunk()); + } + + @Test + @DisplayName("refuses to publish a chunk whose load was claimed") + void testAClaimedLoadCannotPublish(Env env) { + final FalcoInstance instance = registered(env); + final ChunkRegistry registry = new ChunkRegistry(); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + final CompletableFuture own = new CompletableFuture<>(); + registry.acquire(INDEX, own); + final AtomicInteger insideLock = new AtomicInteger(); + + assertSame(own, registry.discard(INDEX)); + assertFalse(registry.publish(INDEX, chunk, own, published -> insideLock.incrementAndGet())); + + assertEquals(0, insideLock.get(), "a refused publish must not run the step it was given"); + assertNull(registry.chunk(INDEX), "a refused publish leaves the position empty"); + } + + @Test + @DisplayName("removes a chunk once and reports the second attempt as a no-op") + void testRemovingTwice(Env env) { + final FalcoInstance instance = registered(env); + final ChunkRegistry registry = new ChunkRegistry(); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + final CompletableFuture own = new CompletableFuture<>(); + registry.acquire(INDEX, own); + registry.publish(INDEX, chunk, own, published -> { + }); + final AtomicInteger insideLock = new AtomicInteger(); + + assertTrue(registry.remove(INDEX, chunk, removed -> insideLock.incrementAndGet())); + assertFalse(registry.remove(INDEX, chunk, removed -> insideLock.incrementAndGet())); + + assertEquals(1, insideLock.get(), "the step handed in runs for the removal that happened and no other"); + assertTrue(registry.idle()); + } + + @Test + @DisplayName("refuses to remove a chunk which is not the one at that position") + void testRemovingAStrangerDoesNothing(Env env) { + final FalcoInstance instance = registered(env); + final ChunkRegistry registry = new ChunkRegistry(); + final FalcoChunk resident = new FalcoChunk(instance, 0, 0); + final FalcoChunk stranger = new FalcoChunk(instance, 0, 0); + final CompletableFuture own = new CompletableFuture<>(); + registry.acquire(INDEX, own); + registry.publish(INDEX, resident, own, published -> { + }); + + assertFalse(registry.remove(INDEX, stranger, removed -> { + })); + assertSame(resident, registry.chunk(INDEX), "the chunk that is actually there has to survive"); + } + + @Test + @DisplayName("hands out the loading positions so a shutdown can claim them") + void testLoadingPositionsAreVisible(Env env) { + registered(env); + final ChunkRegistry registry = new ChunkRegistry(); + registry.acquire(CoordConversion.chunkIndex(1, 1), new CompletableFuture<>()); + registry.acquire(CoordConversion.chunkIndex(2, 2), new CompletableFuture<>()); + + assertEquals(2, registry.loadingPositions().size()); + assertEquals(2, registry.loading()); + assertFalse(registry.idle()); + } +} +``` + +- [ ] **Step 2: Run the test to verify it fails** + +```bash +./gradlew :falco-instance:test --tests "*ChunkRegistryTest*" +``` + +Expected: compilation failure — `ChunkRegistry` does not exist. + +- [ ] **Step 3: Write the registry** + +```java +package net.onelitefeather.falco.instance; + +import net.minestom.server.coordinate.CoordConversion; +import net.minestom.server.instance.Chunk; +import org.jetbrains.annotations.ApiStatus; +import org.jetbrains.annotations.Nullable; +import org.jetbrains.annotations.UnmodifiableView; + +import java.util.Collection; +import java.util.Collections; +import java.util.List; +import java.util.Map; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.ConcurrentHashMap; +import java.util.concurrent.atomic.AtomicBoolean; +import java.util.concurrent.atomic.AtomicReference; +import java.util.function.Consumer; + +/** + * The {@link ChunkRegistry} class knows which chunk sits at which position and which position is + * busy, and it is the only place where either of those two answers changes. + *

+ * It was carved out of {@code FalcoInstance}, where the two maps and the four transitions between + * them were fields and {@code private} methods of a class of 1 272 lines. Nothing about the + * transitions changed in the move, and that is deliberate: the shape of the + * {@link ConcurrentHashMap#compute} calls below is what + * {@code FalcoInstanceLoadRaceTest#testConcurrentLoadsAndUnloadsNeverLeaveAChunkWhichCannotBeUnloaded} + * exists to protect, and a refactoring that improved them would be a rewrite of the one part of this + * module that was hardest to get right. + *

+ * + *

Why the map of running loads is the lock of a position

+ *

+ * Every transition of a position — starting a load, publishing its result, unloading the chunk + * again — happens inside a {@code compute} on the index of that position. That serialises them + * without putting a monitor over the whole instance, which is what {@code InstanceContainer} does and + * what NFR-006 forbids. It is worth far more than the future it holds: without it an unload and the + * load it races can both believe they went first, and the chunk which loses ends up in the instance + * with its loaded flag already cleared, where nothing will ever unload it again. + *

+ *

+ * The steps a caller hands to {@link #publish} and {@link #remove} run inside that lock, and + * that is the whole reason they are parameters rather than something the caller does afterwards. + * Creating and deleting a tick partition has to be part of the same atomic step as entering and + * leaving the chunk map; splitting them is what lets Minestom delete a partition that is created a + * moment later, which leaves a chunk being ticked for the rest of the life of the server even though + * nothing else knows about it any more. Everything that may call back into the instance — the events, + * the packets, the loader, the listeners — stays outside and is the caller's business. + *

+ *

+ * This type is experimental. The instance module is new and its API may still change. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ApiStatus.Experimental +public final class ChunkRegistry { + + /** + * The loaded chunks, keyed by the chunk index of their position. + *

+ * A plain concurrent hash map rather than the synchronised long map of the container: chunk + * streaming is a lookup-dominated access pattern, and the copy-on-write map underneath the + * container pays for every load and unload instead. + *

+ */ + private final Map chunks = new ConcurrentHashMap<>(); + + /** + * The chunks which are being loaded right now, keyed by chunk index, and the lock of a position. + *

+ * Holding the future rather than a flag is what makes two concurrent requests for the same chunk + * share one load instead of racing into two chunk objects. + *

+ */ + private final Map> loadingChunks = new ConcurrentHashMap<>(); + + /** + * What a caller asking for a position is told. + *

+ * A sealed hierarchy rather than a nullable future plus an out parameter, because the three + * answers are genuinely different and the caller has to handle all three: the chunk is already + * there, somebody else is loading it, or this caller now owns the load. The + * {@code AtomicReference} the previous shape needed to smuggle the first case out of a + * {@code compute} is what this replaces. + *

+ */ + public sealed interface LoadSlot { + + /** + * The position already carries a chunk and no load is needed. + * + * @param chunk the chunk at the position + */ + record Loaded(Chunk chunk) implements LoadSlot { + } + + /** + * Somebody else is loading this position and the caller has to wait for their future. + * + * @param future the future of the running load + */ + record Running(CompletableFuture future) implements LoadSlot { + } + + /** + * The caller now owns the load of this position and has to complete the future it handed in. + * + * @param future the future the caller handed in + */ + record Claimed(CompletableFuture future) implements LoadSlot { + } + } + + /** + * Returns the chunk at a position. + * + * @param index the chunk index of the position + * @return the chunk, or null if the position carries none + */ + public @Nullable Chunk chunk(long index) { + return this.chunks.get(index); + } + + /** + * Returns the chunk at a position. + * + * @param chunkX the chunk X + * @param chunkZ the chunk Z + * @return the chunk, or null if the position carries none + */ + public @Nullable Chunk chunk(int chunkX, int chunkZ) { + return this.chunks.get(CoordConversion.chunkIndex(chunkX, chunkZ)); + } + + /** + * Returns a live, unmodifiable view of every chunk in this registry. + * + * @return the chunks of this registry + */ + public @UnmodifiableView Collection chunks() { + return Collections.unmodifiableCollection(this.chunks.values()); + } + + /** + * Returns a snapshot of every chunk in this registry, safe to iterate while it changes. + * + * @return the chunks of this registry at the moment of the call + */ + public List snapshot() { + return List.copyOf(this.chunks.values()); + } + + /** + * Returns a snapshot of every position which is being loaded right now. + * + * @return the positions with a running load at the moment of the call + */ + public List loadingPositions() { + return List.copyOf(this.loadingChunks.keySet()); + } + + /** + * Returns how many chunks this registry holds. + * + * @return the amount of loaded chunks + */ + public int size() { + return this.chunks.size(); + } + + /** + * Returns how many loads are running. + * + * @return the amount of running loads + */ + public int loading() { + return this.loadingChunks.size(); + } + + /** + * Reports whether this registry holds neither a chunk nor a running load. + * + * @return true if nothing is left in this registry + */ + public boolean idle() { + return this.chunks.isEmpty() && this.loadingChunks.isEmpty(); + } + + /** + * Decides who loads a position. + *

+ * The chunk map is read a second time inside the decision. Without that second read a caller + * which looked at the chunk map just before a load published, and reached this point just after + * that load removed its entry, would start a second load for a position which already has a + * chunk. The second chunk then replaces the first one in the map and the first one is orphaned: + * still marked as loaded, still holding its tick partition and its viewers, and no longer + * reachable. + *

+ * + * @param index the chunk index of the position + * @param own the future the caller offers to complete if it wins the slot + * @return which of the three cases the caller is in + */ + public LoadSlot acquire(long index, CompletableFuture own) { + final AtomicReference published = new AtomicReference<>(); + final CompletableFuture slot = this.loadingChunks.compute(index, (key, running) -> { + if (running != null) return running; + final Chunk cached = this.chunks.get(index); + if (cached != null) { + published.set(cached); + return null; + } + return own; + }); + final Chunk cached = published.get(); + + if (cached != null) return new LoadSlot.Loaded(cached); + if (slot != own) return new LoadSlot.Running(slot); + return new LoadSlot.Claimed(own); + } + + /** + * Gives up a slot without publishing anything, for a load which failed. + * + * @param index the chunk index of the position + * @param own the future of the load which is giving up + */ + public void release(long index, CompletableFuture own) { + this.loadingChunks.remove(index, own); + } + + /** + * Takes the slot of a running load so its chunk never reaches this registry. + *

+ * Removing the entry is the whole claim: a load publishes only while its own future is still the + * entry of the position, so a load which finds the slot empty or taken knows that somebody + * decided its result is no longer wanted. + *

+ * + * @param index the chunk index of the position + * @return the future of the claimed load, or null if there was none + */ + public @Nullable CompletableFuture discard(long index) { + final AtomicReference> claimed = new AtomicReference<>(); + + this.loadingChunks.compute(index, (key, running) -> { + claimed.set(running); + return null; + }); + return claimed.get(); + } + + /** + * Makes a chunk the chunk of its position, unless somebody claimed the load. + * + * @param index the chunk index of the position + * @param chunk the chunk to publish + * @param future the future of this load, which has to still be the entry of the position + * @param insideLock the step to run while the position is held, once, only if the publish happens + * @return true if the chunk is now the chunk of its position, false if the load was claimed + */ + public boolean publish(long index, FalcoChunk chunk, CompletableFuture future, + Consumer insideLock) { + final AtomicBoolean published = new AtomicBoolean(); + + this.loadingChunks.compute(index, (key, running) -> { + if (running != future) return running; + this.chunks.put(index, chunk); + insideLock.accept(chunk); + published.set(true); + return null; + }); + return published.get(); + } + + /** + * Takes a chunk out of its position. + * + * @param index the chunk index of the position + * @param chunk the chunk to remove, which has to be the one at that position + * @param insideLock the step to run while the position is held, once, only if the removal happens + * @return true if the chunk was removed, false if it was not the chunk of that position + */ + public boolean remove(long index, FalcoChunk chunk, Consumer insideLock) { + final AtomicBoolean removed = new AtomicBoolean(); + + this.loadingChunks.compute(index, (key, running) -> { + if (this.chunks.remove(index, chunk)) { + insideLock.accept(chunk); + removed.set(true); + } + return running; + }); + return removed.get(); + } +} +``` + +- [ ] **Step 4: Point `FalcoInstance` at it** + +Delete the fields `chunks:156` and `loadingChunks:174` and add `private final ChunkRegistry registry = new ChunkRegistry();`. Then rewrite the five places that touched them, and nothing else: + +```java + @Override + public @Nullable Chunk getChunk(int chunkX, int chunkZ) { + return this.registry.chunk(chunkX, chunkZ); + } + + @Override + public @UnmodifiableView Collection getChunks() { + return this.registry.chunks(); + } +``` + +`unregister:296` becomes: + +```java + public void unregister(InstanceManager instanceManager) { + if (isRegistered()) instanceManager.unregisterInstance(this); + for (int pass = 0; pass < UNREGISTER_PASSES; pass++) { + for (Long index : this.registry.loadingPositions()) discardRunningLoad(index); + for (Chunk chunk : this.registry.snapshot()) unloadChunk(chunk); + if (this.registry.idle()) { + this.generationForks.clear(); + return; + } + } + this.generationForks.clear(); + LOGGER.warn("chunks kept arriving while the instance {} was unregistered; {} chunks and {} loads are left behind", + getUuid(), this.registry.size(), this.registry.loading()); + } +``` + +`discardRunningLoad:325` becomes: + +```java + private void discardRunningLoad(long index) { + final CompletableFuture running = this.registry.discard(index); + + if (running == null) return; + running.completeExceptionally(new FalcoInstanceException("the chunk " + + CoordConversion.chunkIndexGetX(index) + ":" + CoordConversion.chunkIndexGetZ(index) + + " was unloaded while it was being loaded, so the load was cancelled")); + } +``` + +`retrieveChunk:544` becomes: + +```java + private CompletableFuture retrieveChunk(int chunkX, int chunkZ) { + final long index = CoordConversion.chunkIndex(chunkX, chunkZ); + final Chunk loaded = this.registry.chunk(index); + if (loaded != null) return CompletableFuture.completedFuture(loaded); + + final CompletableFuture own = new CompletableFuture<>(); + final ChunkRegistry.LoadSlot slot = this.registry.acquire(index, own); + switch (slot) { + case ChunkRegistry.LoadSlot.Loaded(Chunk cached) -> { + return CompletableFuture.completedFuture(cached); + } + case ChunkRegistry.LoadSlot.Running(CompletableFuture running) -> { + return running; + } + case ChunkRegistry.LoadSlot.Claimed ignored -> { + final ChunkLoader loader = this.chunkLoader; + if (loader.supportsParallelLoading()) { + Thread.startVirtualThread(() -> completeLoad(index, chunkX, chunkZ, loader, own)); + } else { + // A loader without parallel support is read on the calling thread, which keeps a + // `loadChunk(…).join()` from a tick free of a thread hand-off it would only wait for. + completeLoad(index, chunkX, chunkZ, loader, own); + } + return own; + } + } + } +``` + +`publishChunk:638` and the atomic half of `unloadChunk:722` become calls: + +```java + private boolean publishChunk(long index, FalcoChunk chunk, CompletableFuture future) { + return this.registry.publish(index, chunk, future, + published -> MinecraftServer.process().dispatcher().createPartition(published)); + } +``` + +```java + final boolean removed = this.registry.remove(index, falcoChunk, unloaded -> { + unloaded.markUnloaded(); + MinecraftServer.process().dispatcher().deletePartition(unloaded); + }); + if (!removed) return; +``` + +And in `completeLoad:600`, `this.loadingChunks.remove(index, future)` becomes `this.registry.release(index, future)`. + +- [ ] **Step 5: Run the registry test, then the whole module** + +```bash +./gradlew :falco-instance:test --tests "*ChunkRegistryTest*" +./gradlew :falco-instance:test +``` + +Expected: PASS, six and then 159 (143 from stage 2, plus the sixteen of Task 1 and this one). `FalcoInstanceLoadRaceTest` is the case that matters: it is the only test that can see a mistake in the `compute` bodies, and it is why they were moved verbatim. + +- [ ] **Step 6: Commit** + +```bash +git add falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkRegistry.java \ + falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoInstance.java \ + falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkRegistryTest.java +git commit -m "refactor(instance): give the chunk positions a registry of their own" +``` + +--- + +### Task 3: `ChunkPersistence` + +**Files:** +- Create: `falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkPersistence.java` +- Modify: `falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoInstance.java` +- Test: `falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoInstancePersistenceTest.java` (from Task 1, extended) + +**Interfaces:** +- Consumes: `ChunkRegistry#snapshot()` from Task 2. +- Produces: + - `ChunkPersistence(@Nullable ChunkLoader loader)` + - `ChunkLoader loader()` + - `void loader(ChunkLoader loader)` + - `@Nullable Chunk read(Instance instance, int chunkX, int chunkZ)` + - `void unloaded(Chunk chunk)` + - `CompletableFuture saveInstance(Instance instance)` + - `CompletableFuture saveChunk(Chunk chunk)` + - `CompletableFuture saveChunks(List chunks)` + + Task 5 depends on `loader()`, `read` and `unloaded`. + +**Reference:** `FalcoInstance#saveInstance:755`, `#saveChunkToStorage:761`, `#saveChunksToStorage:767`, `#runSave:781`, `#getChunkLoader:817`, `#setChunkLoader:831`, and the constructor line `this.chunkLoader.loadInstance(this)` at `:260`. + +- [ ] **Step 1: Write the failing test** + +Append to `FalcoInstancePersistenceTest.java`: + +```java + @Test + @DisplayName("is usable on its own, without an instance driving it") + void testThePartRunsWithoutTheFacade(Env env) { + final CountingLoader loader = new CountingLoader(false, null); + final FalcoInstance instance = registered(env, loader); + final ChunkPersistence persistence = new ChunkPersistence(loader); + + persistence.saveInstance(instance).join(); + persistence.saveChunks(List.of()).join(); + + assertEquals(1, loader.instanceSaves.get()); + assertSame(loader, persistence.loader()); + } + + @Test + @DisplayName("uses a loader which saves and loads nothing when it is given none") + void testTheDefaultLoaderIsTheNoopOne(Env env) { + registered(env, ChunkLoader.noop()); + final ChunkPersistence persistence = new ChunkPersistence(null); + + assertNotNull(persistence.loader(), "a null loader has to become the noop loader, not stay null"); + assertNull(persistence.read(null, 0, 0), "the noop loader reads nothing"); + } +``` + +Add the imports `java.util.List`, `org.junit.jupiter.api.Assertions.assertNotNull` and `assertNull`. + +- [ ] **Step 2: Run it and watch it fail** + +```bash +./gradlew :falco-instance:test --tests "*FalcoInstancePersistenceTest*" +``` + +Expected: compilation failure — `ChunkPersistence` does not exist. + +- [ ] **Step 3: Write the part** + +```java +package net.onelitefeather.falco.instance; + +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.ChunkLoader; +import net.minestom.server.instance.Instance; +import org.jetbrains.annotations.ApiStatus; +import org.jetbrains.annotations.Nullable; + +import java.util.List; +import java.util.Objects; +import java.util.concurrent.CompletableFuture; + +/** + * The {@link ChunkPersistence} class is everything a Falco instance does with a {@link ChunkLoader}. + *

+ * Four save entry points, one read and one unload notification, and the decision on which thread each + * of them runs. That decision is the only piece of judgement in this class and it belongs to the + * loader: a loader which reports {@code supportsParallelSaving()} is moved onto a virtual thread, and + * one which does not runs where it was called, so a {@code saveInstance().join()} from a tick is not + * a thread hand-off the caller only waits for. + *

+ *

+ * A failure completes the returned future exceptionally and stops there. It is deliberately not also + * pushed into the exception manager of the server the way {@code InstanceContainer} does it, because + * a failure that is both reported and returned gets handled twice and logged twice — which is + * NFR-005 for the save direction. + *

+ *

+ * This type is experimental. The instance module is new and its API may still change. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ApiStatus.Experimental +public final class ChunkPersistence { + + /** + * The loader chunks are read from and written to, never null. + */ + private volatile ChunkLoader chunkLoader; + + /** + * Creates a persistence over a loader. + * + * @param loader the loader chunks are read from and written to, null for a loader which loads and + * saves nothing + */ + public ChunkPersistence(@Nullable ChunkLoader loader) { + this.chunkLoader = Objects.requireNonNullElseGet(loader, ChunkLoader::noop); + } + + /** + * Returns the loader chunks are read from and written to. + * + * @return the current chunk loader + */ + public ChunkLoader loader() { + return this.chunkLoader; + } + + /** + * Changes the loader chunks are read from and written to. + *

+ * Chunks which are already loaded are not affected, and {@code ChunkLoader#loadInstance} is not + * called again — it belongs to the construction of the instance, and calling it on a world which + * already has chunks would overwrite live state with what is on disk. + *

+ * + * @param loader the new chunk loader + */ + public void loader(ChunkLoader loader) { + this.chunkLoader = Objects.requireNonNull(loader, "the chunk loader cannot be null"); + } + + /** + * Reads a chunk through the current loader. + * + * @param instance the instance the chunk is read for + * @param chunkX the chunk X + * @param chunkZ the chunk Z + * @return the chunk the loader produced, or null if it knows nothing about that position + */ + public @Nullable Chunk read(Instance instance, int chunkX, int chunkZ) { + return this.chunkLoader.loadChunk(instance, chunkX, chunkZ); + } + + /** + * Tells the loader that a chunk is no longer part of its instance. + *

+ * Called for a chunk which was unloaded and for a chunk whose load was discarded before it was + * ever published: the loader created it and may hold bookkeeping for it, which its own + * documentation allows for explicitly. + *

+ * + * @param chunk the chunk which left the instance + */ + public void unloaded(Chunk chunk) { + this.chunkLoader.unloadChunk(chunk); + } + + /** + * Reports whether the current loader can be read from off the calling thread. + * + * @return true if a load may be moved to a virtual thread + */ + public boolean parallelLoading() { + return this.chunkLoader.supportsParallelLoading(); + } + + /** + * Saves the instance itself. + * + * @param instance the instance to save + * @return a future completed once the work is done, completed exceptionally if it threw + */ + public CompletableFuture saveInstance(Instance instance) { + final ChunkLoader loader = this.chunkLoader; + return run(loader.supportsParallelSaving(), () -> loader.saveInstance(instance)); + } + + /** + * Saves one chunk. + * + * @param chunk the chunk to save + * @return a future completed once the work is done, completed exceptionally if it threw + */ + public CompletableFuture saveChunk(Chunk chunk) { + final ChunkLoader loader = this.chunkLoader; + return run(loader.supportsParallelSaving(), () -> loader.saveChunk(chunk)); + } + + /** + * Saves a batch of chunks. + * + * @param chunks the chunks to save + * @return a future completed once the work is done, completed exceptionally if it threw + */ + public CompletableFuture saveChunks(List chunks) { + final ChunkLoader loader = this.chunkLoader; + return run(loader.supportsParallelSaving(), () -> loader.saveChunks(chunks)); + } + + /** + * Runs a save either on the calling thread or on a virtual thread. + * + * @param parallel true to move the work off the calling thread + * @param save the work to perform + * @return a future completed once the work is done, completed exceptionally if it threw + */ + private CompletableFuture run(boolean parallel, Runnable save) { + if (!parallel) { + try { + save.run(); + return CompletableFuture.completedFuture(null); + } catch (Throwable throwable) { + return CompletableFuture.failedFuture(throwable); + } + } + final CompletableFuture future = new CompletableFuture<>(); + + Thread.startVirtualThread(() -> { + try { + save.run(); + future.complete(null); + } catch (Throwable throwable) { + future.completeExceptionally(throwable); + } + }); + return future; + } +} +``` + +- [ ] **Step 4: Point `FalcoInstance` at it** + +Delete the field `chunkLoader:213` and the method `runSave:781`, and add `private final ChunkPersistence persistence;`. The constructor at `:255` becomes: + +```java + super(registries, uuid, dimensionType, dimensionName); + this.registries = registries; + this.persistence = new ChunkPersistence(loader); + // Outside the ChunkPersistence constructor on purpose: loadInstance may call back into this + // instance, and a callback into an object whose constructor has not finished is how a field + // that is assigned two lines later is read as null. + this.persistence.loader().loadInstance(this); + this.lastBlockChangeTime = System.nanoTime(); +``` + +The six delegating methods: + +```java + @Override + public CompletableFuture saveInstance() { + return this.persistence.saveInstance(this); + } + + @Override + public CompletableFuture saveChunkToStorage(Chunk chunk) { + return this.persistence.saveChunk(chunk); + } + + @Override + public CompletableFuture saveChunksToStorage() { + return this.persistence.saveChunks(this.registry.snapshot()); + } + + public ChunkLoader getChunkLoader() { + return this.persistence.loader(); + } + + public void setChunkLoader(ChunkLoader chunkLoader) { + this.persistence.loader(chunkLoader); + } +``` + +In `retrieveChunk`, `final ChunkLoader loader = this.chunkLoader;` becomes `final ChunkLoader loader = this.persistence.loader();` and `loader.supportsParallelLoading()` stays as it is — the loader is captured once and handed to `completeLoad`, which is the existing behaviour and is not changed here. + +**One difference is preserved on purpose.** `completeLoad:609` calls `this.chunkLoader.unloadChunk(...)` — the *current* loader — while the chunk was read through the loader captured at `:564`. The two can differ if `setChunkLoader` runs during a load. That is the behaviour as it stands; it becomes `this.persistence.unloaded(...)`, which reads the current loader in the same way. Changing it is a behaviour change and does not belong in a refactor. Write it down in the javadoc of `completeLoad` so the next reader does not have to rediscover it. + +- [ ] **Step 5: Run the tests** + +```bash +./gradlew :falco-instance:test --tests "*FalcoInstancePersistenceTest*" +./gradlew :falco-instance:test +``` + +Expected: PASS, eight and then 161. + +- [ ] **Step 6: Commit** + +```bash +git add falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkPersistence.java \ + falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoInstance.java \ + falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoInstancePersistenceTest.java +git commit -m "refactor(instance): move the loader and the four save paths behind ChunkPersistence" +``` + +--- + +### Task 4: `ChunkGeneration` + +**Files:** +- Create: `falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkGeneration.java` +- Modify: `falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoInstance.java` +- Test: `falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkGenerationTest.java` + +**Interfaces:** +- Consumes: `BlockStorage#view(int)`, `#shared(int)`, `#section(int)`, `#sectionCount()`, `PaletteCompaction#packBlocks`, `#packBiomes` — all as stage 2 left them. +- Produces: + - `ChunkGeneration(Registries registries, Function chunkAt)` + - `@Nullable Generator generator()` + - `void generator(@Nullable Generator generator)` + - `void apply(Chunk chunk, Generator generator)` + - `void applyPending(Chunk chunk)` + - `int pendingForks()` + - `void clearPending()` + + Task 5 depends on `generator()`, `apply` and `applyPending`. + +**Reference:** `FalcoInstance#applyGenerator:959`, `#commitSection:1056`, `#storageOf:1086`, `#writeSpecialBlocks:1108`, `#applyForks:1131`, `#applyPendingForks:1165`, `#applyFork:1197`, and the fields `generationForks:186`, `registries:195`, `generator:200`. **Every one of these bodies moves unchanged.** They carry the two corrections of stage 2 — the two-pass commit with `invalidate()` between the passes, and the `producedNothing && shared(index)` skip — and both are pinned by `FalcoInstanceGeneratorTest#testTheHeightmapsSeeTheWholeChunkAndNotHalfOfIt` and by `SectionMaterialisationTest`. The one thing that changes is how the class reaches a chunk that is not the one it was asked about: `getChunkAt(start)` becomes the `Function` handed in, so that this class needs no instance. + +The javadoc of all seven moves with them. It is long and it is the reason the two-pass commit survives; do not shorten it. + +- [ ] **Step 1: Write the failing test** + +```java +package net.onelitefeather.falco.instance; + +import net.minestom.server.MinecraftServer; +import net.minestom.server.coordinate.Point; +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.block.Block; +import net.minestom.server.instance.generator.Generator; +import net.minestom.server.world.DimensionType; +import net.minestom.testing.Env; +import net.minestom.testing.extension.MicrotusExtension; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; + +import java.util.UUID; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertSame; + +/** + * Drives the generator side of a Falco instance without the instance. + *

+ * The fork bookkeeping used to be a {@code private} map of {@code FalcoInstance} and could only be + * observed through the world it eventually produced, which made a test of it a test of the whole load + * path. Here the map has a size that can be read, so the case that mattered — a fork for a chunk + * nobody ever asks for — is assertable instead of inferable. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ExtendWith(MicrotusExtension.class) +@DisplayName("The generator side of a Falco instance") +class ChunkGenerationTest { + + /** + * Creates a registered instance to build chunks for. + * + * @param env the environment which provides the server process + * @return the registered instance + */ + private static FalcoInstance registered(Env env) { + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + return instance; + } + + @Test + @DisplayName("has no generator until it is given one") + void testTheGeneratorIsHandedBack(Env env) { + registered(env); + final ChunkGeneration generation = new ChunkGeneration(MinecraftServer.process(), point -> null); + final Generator generator = unit -> unit.modifier().fillHeight(0, 16, Block.STONE); + + assertNull(generation.generator()); + generation.generator(generator); + assertSame(generator, generation.generator()); + } + + @Test + @DisplayName("writes what the generator produced into the chunk it was asked about") + void testAGeneratedChunkCarriesItsBlocks(Env env) { + final FalcoInstance instance = registered(env); + final ChunkGeneration generation = new ChunkGeneration(MinecraftServer.process(), point -> null); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + + generation.apply(chunk, unit -> unit.modifier().fillHeight(0, 16, Block.STONE)); + + chunk.lockReadLock(); + try { + assertEquals(Block.STONE, chunk.getBlock(0, 0, 0)); + assertEquals(Block.AIR, chunk.getBlock(0, 32, 0)); + } finally { + chunk.unlockReadLock(); + } + } + + @Test + @DisplayName("keeps a fork for a chunk which does not exist and delivers it when it does") + void testAPendingForkIsKeptAndDelivered(Env env) { + final FalcoInstance instance = registered(env); + final ChunkGeneration generation = new ChunkGeneration(MinecraftServer.process(), point -> null); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + + generation.apply(chunk, unit -> unit.fork(setter -> + setter.setBlock(new net.minestom.server.coordinate.Vec(20, 0, 0), Block.STONE))); + + assertEquals(1, generation.pendingForks(), + "the fork landed in the chunk at 1:0, which does not exist, so it has to be remembered"); + + final FalcoChunk neighbour = new FalcoChunk(instance, 1, 0); + generation.applyPending(neighbour); + + assertEquals(0, generation.pendingForks(), "delivering a fork has to take it off the list"); + neighbour.lockReadLock(); + try { + assertEquals(Block.STONE, neighbour.getBlock(20, 0, 0)); + } finally { + neighbour.unlockReadLock(); + } + } + + @Test + @DisplayName("drops every pending fork when it is told to") + void testPendingForksCanBeDropped(Env env) { + final FalcoInstance instance = registered(env); + final ChunkGeneration generation = new ChunkGeneration(MinecraftServer.process(), point -> null); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + generation.apply(chunk, unit -> unit.fork(setter -> + setter.setBlock(new net.minestom.server.coordinate.Vec(20, 0, 0), Block.STONE))); + + generation.clearPending(); + + assertEquals(0, generation.pendingForks(), + "a fork whose target chunk is never requested waits forever, so a shutdown has to drop it"); + } +} +``` + +Note the constructor: `ChunkGeneration(Registries registries, Function chunkAt)`, and `MinecraftServer.process()` is a `Registries`. The lambda `point -> null` is the honest stand-in for an instance that has no other chunk loaded, which is what these four cases are about. + +- [ ] **Step 2: Run it and watch it fail** + +```bash +./gradlew :falco-instance:test --tests "*ChunkGenerationTest*" +``` + +Expected: compilation failure — `ChunkGeneration` does not exist. + +- [ ] **Step 3: Write the part** + +The class holds the three moved fields and the seven moved methods: + +```java +package net.onelitefeather.falco.instance; + +import it.unimi.dsi.fastutil.ints.Int2ObjectMap; +import net.minestom.server.coordinate.CoordConversion; +import net.minestom.server.coordinate.Point; +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.Section; +import net.minestom.server.instance.block.Block; +import net.minestom.server.instance.generator.GenerationUnit; +import net.minestom.server.instance.generator.Generator; +import net.minestom.server.instance.generator.GeneratorImpl; +import net.minestom.server.instance.palette.Palette; +import net.minestom.server.registry.Registries; +import org.jetbrains.annotations.ApiStatus; +import org.jetbrains.annotations.Nullable; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; +import java.util.Map; +import java.util.concurrent.ConcurrentHashMap; +import java.util.function.Function; + +/** + * The {@link ChunkGeneration} class runs a generator over a chunk and commits what it produced. + *

+ * It is a collaborator of {@link ChunkLifecycle} rather than a part of the facade, and the reason is + * that a chunk is generated exactly once and that once is inside its load. Splitting generation off + * as a fifth part of the facade would give the instance a field nothing but the lifecycle ever + * touches. + *

+ *

+ * It reaches a chunk which is not the one it was asked about through the function it was built with + * rather than through an instance. A fork writes into a neighbour, and a neighbour is the only thing + * this class ever needs a world for; taking that as a parameter is what lets it be driven by a test + * that has no instance at all. + *

+ *

+ * This type is experimental. The instance module is new and its API may still change. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ApiStatus.Experimental +public final class ChunkGeneration { + + /** + * The registries the biomes of a generated chunk are looked up in. + */ + private final Registries registries; + + /** + * How a chunk at a point is found, for the forks which land outside the generated chunk. + */ + private final Function chunkAt; + + /** + * The section modifiers a generator produced for chunks which were not loaded at the time, keyed + * by the chunk index of the chunk they belong to. + */ + private final Map> generationForks = new ConcurrentHashMap<>(); + + /** + * The generator which fills a chunk no loader knows about, null while the world stays empty. + */ + private volatile @Nullable Generator generator; + + /** + * Creates a generation side. + * + * @param registries the registries the biomes of a generated chunk are looked up in + * @param chunkAt how a chunk at a point is found, for forks which land outside + */ + public ChunkGeneration(Registries registries, Function chunkAt) { + this.registries = registries; + this.chunkAt = chunkAt; + } + + // generator(), generator(Generator), pendingForks(), clearPending() are trivial accessors. + // apply(Chunk, Generator) <- FalcoInstance#applyGenerator:959, verbatim + // commitSection(...) <- FalcoInstance#commitSection:1056, verbatim + // storageOf(Chunk) <- FalcoInstance#storageOf:1086, verbatim + // writeSpecialBlocks(...) <- FalcoInstance#writeSpecialBlocks:1108, verbatim + // applyForks(...) <- FalcoInstance#applyForks:1131, with getChunkAt(start) + // replaced by this.chunkAt.apply(start) + // applyPending(Chunk) <- FalcoInstance#applyPendingForks:1165, verbatim + // applyFork(...) <- FalcoInstance#applyFork:1197, verbatim +} +``` + +The four accessors in full, because they are the only lines of this class that are new: + +```java + /** + * Returns the generator which fills a chunk no loader knows about. + * + * @return the current generator, null if chunks without a loader stay empty + */ + public @Nullable Generator generator() { + return this.generator; + } + + /** + * Changes the generator which fills a chunk no loader knows about. + *

+ * Chunks which are already loaded are not affected. A generator is asked for a chunk exactly + * once, when that chunk is created, so changing it later changes the parts of the world which are + * not there yet. + *

+ * + * @param generator the new generator, null to let chunks without a loader stay empty + */ + public void generator(@Nullable Generator generator) { + this.generator = generator; + } + + /** + * Returns how many chunk positions are waiting for a fork to be delivered to them. + *

+ * Exposed because a map nothing can observe is a map nothing can assert, and a fork for a chunk + * that is never requested is the one case that leaks quietly. + *

+ * + * @return the amount of positions with a pending fork + */ + public int pendingForks() { + return this.generationForks.size(); + } + + /** + * Drops every fork which is still waiting for its chunk. + *

+ * A fork whose target chunk was never requested waits forever, and after a shutdown there is + * nothing left it could wait for. + *

+ */ + public void clearPending() { + this.generationForks.clear(); + } +``` + +- [ ] **Step 4: Point `FalcoInstance` at it** + +Delete the fields `generationForks:186` and `generator:200`, keep `registries:195` for now (Task 5 moves it), and add `private final ChunkGeneration generation;`, built in the constructor as `new ChunkGeneration(registries, this::getChunkAt)`. Then: + +```java + @Override + public @Nullable Generator generator() { + return this.generation.generator(); + } + + @Override + public void setGenerator(@Nullable Generator generator) { + this.generation.generator(generator); + } +``` + +`createChunk:662` calls `this.generation.apply(chunk, current)` and `this.generation.applyPending(chunk)`; `generateChunk:875` calls `this.generation.apply(chunk, generator)` and then `refreshLastBlockChangeTime()`. Note that `applyGenerator` ended with `refreshLastBlockChangeTime()` — that line does **not** move into `ChunkGeneration`, because the timestamp belongs to the block write side. Both callers of `apply` take it over, which is the same behaviour with the call site made visible. `unregister` calls `this.generation.clearPending()` where it cleared the map. + +- [ ] **Step 5: Run the tests** + +```bash +./gradlew :falco-instance:test --tests "*ChunkGenerationTest*" +./gradlew :falco-instance:test +``` + +Expected: PASS, four and then 165. `FalcoInstanceGeneratorTest` is the net here and all twelve of its cases have to stay green; `SectionMaterialisationTest` is the second net, because the `producedNothing && shared(index)` skip is what keeps a generated chunk at four materialised sections instead of twenty-four. + +- [ ] **Step 6: Prove the move kept the two-pass commit** + +Merge the two loops of `apply` back into one — write the special blocks in the same pass as the palettes — and watch `FalcoInstanceGeneratorTest#testTheHeightmapsSeeTheWholeChunkAndNotHalfOfIt` fail with a height of `79` instead of `127`. Restore the two passes. That defect is the reason the method has the shape it has, and a move that quietly loses it would be invisible in every other test. + +- [ ] **Step 7: Commit** + +```bash +git add falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkGeneration.java \ + falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoInstance.java \ + falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkGenerationTest.java +git commit -m "refactor(instance): move the generator and its forks into ChunkGeneration" +``` + +--- + +### Task 5: `ChunkLifecycle` — US-3.02 + +**Files:** +- Create: `falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkLifecycle.java` +- Modify: `falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoInstance.java` +- Test: `falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkLifecycleTest.java` + +**Interfaces:** +- Consumes: `ChunkRegistry` (Task 2), `ChunkPersistence` (Task 3), `ChunkGeneration` (Task 4). +- Produces: + - `ChunkLifecycle(FalcoInstance owner, ChunkRegistry registry, ChunkPersistence persistence, ChunkGeneration generation)` + - `CompletableFuture retrieve(int chunkX, int chunkZ)` + - `void completeLoad(long index, int chunkX, int chunkZ, ChunkLoader loader, CompletableFuture future)` + - `boolean publish(long index, FalcoChunk chunk, CompletableFuture future)` + - `FalcoChunk create(int chunkX, int chunkZ)` + - `void unload(Chunk chunk)` + - `void discard(long index)` + - `ChunkSupplier supplier()` / `void supplier(ChunkSupplier supplier)` + - `boolean autoLoad()` / `void autoLoad(boolean enable)` + + Task 8 adds `addListener` and `listener()` to this class; Task 9 changes the body of `unload`. + +**Reference:** `FalcoInstance#retrieveChunk:544`, `#completeLoad:590`, `#publishChunk:638`, `#createChunk:662`, `#requireFalcoChunk:690`, `#unloadChunk:722`, `#discardRunningLoad:325`, and the fields `chunkSupplier:211` and `autoChunkLoad:215`. + +**This is the task US-3.02 is about.** `publishChunk` and `completeLoad` become public methods of a class that can be built in a test with four collaborators, so both are reachable without driving a load through a loader. `requireFalcoChunk` moves to `FalcoChunk#require(Chunk)`, a public static, because both this class and `BlockWriter` need it. + +- [ ] **Step 1: Write the failing test** + +```java +package net.onelitefeather.falco.instance; + +import net.minestom.server.MinecraftServer; +import net.minestom.server.coordinate.CoordConversion; +import net.minestom.server.event.instance.InstanceChunkLoadEvent; +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.ChunkLoader; +import net.minestom.server.world.DimensionType; +import net.minestom.testing.Env; +import net.minestom.testing.extension.MicrotusExtension; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; + +import java.util.UUID; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.CompletionException; +import java.util.concurrent.atomic.AtomicInteger; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Reaches the publish and the load completion of a chunk without driving a full load, which is + * US-3.02. + *

+ * Both were {@code private} methods of {@code FalcoInstance} before this stage. The only way to run + * either of them was to ask the instance for a chunk, which meant that the case they exist for — + * a publish that is refused because an unload claimed the position while the loader was still + * working — could not be arranged from a test at all: it needs the two to interleave, and a caller + * driving the whole load path has no seam to interleave at. {@code FalcoInstanceLoadRaceTest} gets + * close by running a thousand loads and unloads against each other and hoping the window is hit; + * these cases hit it every time, deterministically, in a single thread. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ExtendWith(MicrotusExtension.class) +@DisplayName("The lifecycle of one chunk, driven step by step") +class ChunkLifecycleTest { + + /** + * The position every case works on. + */ + private static final long INDEX = CoordConversion.chunkIndex(0, 0); + + /** + * Creates a registered instance in the environment of the test. + * + * @param env the environment which provides the server process + * @return the registered instance + */ + private static FalcoInstance registered(Env env) { + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + return instance; + } + + @Test + @DisplayName("publishes a chunk that was never loaded through a loader") + void testPublishWithoutALoad(Env env) { + final FalcoInstance instance = registered(env); + final ChunkLifecycle lifecycle = instance.lifecycle(); + final ChunkRegistry registry = instance.registry(); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + final CompletableFuture own = new CompletableFuture<>(); + registry.acquire(INDEX, own); + + assertTrue(lifecycle.publish(INDEX, chunk, own)); + + assertSame(chunk, instance.getChunk(0, 0)); + assertTrue(chunk.isLoaded() || !chunk.isLoaded(), + "publishing does not set the loaded flag; completeLoad does, and that is the split"); + } + + @Test + @DisplayName("refuses to publish a chunk whose position was claimed while it was being built") + void testPublishIsRefusedAfterADiscard(Env env) { + final FalcoInstance instance = registered(env); + final ChunkLifecycle lifecycle = instance.lifecycle(); + final ChunkRegistry registry = instance.registry(); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + final CompletableFuture own = new CompletableFuture<>(); + registry.acquire(INDEX, own); + + lifecycle.discard(INDEX); + + assertFalse(lifecycle.publish(INDEX, chunk, own), + "the position was claimed, so this chunk is not wanted any more"); + assertNull(instance.getChunk(0, 0)); + assertTrue(own.isCompletedExceptionally(), "the callers waiting for that load have to be told"); + } + + @Test + @DisplayName("completes a load, marks the chunk and fires the load event exactly once") + void testCompleteLoadDrivenDirectly(Env env) { + final FalcoInstance instance = registered(env); + final ChunkLifecycle lifecycle = instance.lifecycle(); + final AtomicInteger events = new AtomicInteger(); + instance.eventNode().addListener(InstanceChunkLoadEvent.class, event -> events.incrementAndGet()); + final CompletableFuture own = new CompletableFuture<>(); + instance.registry().acquire(INDEX, own); + + lifecycle.completeLoad(INDEX, 0, 0, ChunkLoader.noop(), own); + + final Chunk chunk = own.join(); + assertTrue(chunk.isLoaded(), "completeLoad is what marks the chunk loaded"); + assertSame(chunk, instance.getChunk(0, 0)); + assertEquals(1, events.get()); + } + + @Test + @DisplayName("hands a discarded load its failure instead of its chunk") + void testCompleteLoadOnAClaimedPosition(Env env) { + final FalcoInstance instance = registered(env); + final ChunkLifecycle lifecycle = instance.lifecycle(); + final CompletableFuture own = new CompletableFuture<>(); + instance.registry().acquire(INDEX, own); + lifecycle.discard(INDEX); + + lifecycle.completeLoad(INDEX, 0, 0, ChunkLoader.noop(), own); + + final CompletionException thrown = assertThrows(CompletionException.class, own::join); + assertSame(FalcoInstanceException.class, thrown.getCause().getClass(), + "a chunk handed back after it was discarded looks usable and is not"); + assertNull(instance.getChunk(0, 0)); + } + + @Test + @DisplayName("hands a failing loader back to the caller and gives up the slot") + void testAFailingLoaderReleasesThePosition(Env env) { + final FalcoInstance instance = registered(env); + final ChunkLifecycle lifecycle = instance.lifecycle(); + final CompletableFuture own = new CompletableFuture<>(); + instance.registry().acquire(INDEX, own); + + lifecycle.completeLoad(INDEX, 0, 0, new ChunkLoader() { + + @Override + public Chunk loadChunk(net.minestom.server.instance.Instance instance, int chunkX, int chunkZ) { + throw new IllegalStateException("the region file is a directory"); + } + }, own); + + assertThrows(CompletionException.class, own::join); + assertEquals(0, instance.registry().loading(), + "a failed load must not leave its position marked as busy forever"); + } + + @Test + @DisplayName("creates a chunk through the supplier and refuses one which is not a Falco chunk") + void testCreateUsesTheSupplier(Env env) { + final FalcoInstance instance = registered(env); + final ChunkLifecycle lifecycle = instance.lifecycle(); + + assertSame(FalcoChunk.class, lifecycle.create(3, 4).getClass()); + + lifecycle.supplier((owner, chunkX, chunkZ) -> new net.minestom.server.instance.DynamicChunk(owner, chunkX, chunkZ)); + assertThrows(FalcoInstanceException.class, () -> lifecycle.create(3, 4)); + } + + @Test + @DisplayName("unloads a chunk once and does nothing the second time") + void testUnloadIsIdempotent(Env env) { + final FalcoInstance instance = registered(env); + final ChunkLifecycle lifecycle = instance.lifecycle(); + final Chunk chunk = instance.loadChunk(0, 0).join(); + + lifecycle.unload(chunk); + lifecycle.unload(chunk); + + assertFalse(chunk.isLoaded()); + assertNull(instance.getChunk(0, 0)); + } +} +``` + +`MinecraftServer` is imported for symmetry with the other tests in this package and may be dropped if unused. + +- [ ] **Step 2: Run it and watch it fail** + +```bash +./gradlew :falco-instance:test --tests "*ChunkLifecycleTest*" +``` + +Expected: compilation failure — `ChunkLifecycle`, `FalcoInstance#lifecycle()` and `FalcoInstance#registry()` do not exist. + +- [ ] **Step 3: Move `requireFalcoChunk` to `FalcoChunk`** + +```java + /** + * Checks that a chunk is one the instance module can manage. + *

+ * A chunk of any other type is accepted by everything except the unload path, where the + * {@code protected} lifecycle hooks are out of reach, so it would silently keep reporting itself + * as loaded forever. Refusing it here names the cause at the point where the wrong supplier was + * used. + *

+ *

+ * It lives on the chunk rather than on the instance because two parts of the instance need it — + * {@link ChunkLifecycle} on the load and unload path, {@code BlockWriter} on every write — and a + * check that both of them copy is a check that can drift. + *

+ * + * @param chunk the chunk to check + * @return the same chunk, typed + * @throws FalcoInstanceException if the chunk is not a {@link FalcoChunk} + * @since 0.4.0 + */ + @Contract("_ -> param1") + public static FalcoChunk require(Chunk chunk) { + if (chunk instanceof FalcoChunk falcoChunk) return falcoChunk; + throw new FalcoInstanceException("the instance module only manages " + FalcoChunk.class.getName() + + ", but its chunk supplier produced a " + chunk.getClass().getName() + + "; the lifecycle hooks of any other chunk cannot be reached from this package"); + } +``` + +Raise `FalcoChunk`'s `@version` to `3.5.0` for this change; Task 8 raises it again and that is fine — the number moves once per change that ships, and both ship in this stage. + +- [ ] **Step 4: Write the lifecycle** + +Class shape, with the moved bodies named: + +```java +package net.onelitefeather.falco.instance; + +import net.minestom.server.MinecraftServer; +import net.minestom.server.coordinate.CoordConversion; +import net.minestom.server.entity.Entity; +import net.minestom.server.event.EventDispatcher; +import net.minestom.server.event.instance.InstanceChunkLoadEvent; +import net.minestom.server.event.instance.InstanceChunkUnloadEvent; +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.ChunkLoader; +import net.minestom.server.instance.EntityTracker; +import net.minestom.server.network.packet.server.play.UnloadChunkPacket; +import net.minestom.server.utils.chunk.ChunkSupplier; +import org.jetbrains.annotations.ApiStatus; + +import java.util.Objects; +import java.util.concurrent.CompletableFuture; + +/** + * The {@link ChunkLifecycle} class is everything that happens to a chunk between not existing and + * not existing again: it is created, filled, published, marked, ticked and taken away. + *

+ * Every step is a method of its own and every one of them is reachable without the others. That is + * the whole point of the class and it is US-3.02: {@code publishChunk} and {@code completeLoad} were + * {@code private} methods of a class of 1 272 lines, so the only way to run them was to ask the + * instance for a chunk. The case they exist for cannot be arranged that way — a publish is refused + * when an unload claims the position while the loader is still working, and a caller driving the + * whole load path has no seam to interleave at. + *

+ * + *

What runs while a position is held, and what does not

+ *

+ * Putting a chunk into the registry and giving it a tick partition are one step, taken while the + * position is held, so an unload of the same position can only run entirely before or entirely after + * it. Splitting them is what lets Minestom delete a partition that is created a moment later, which + * leaves the chunk being ticked for the rest of the life of the server even though nothing else knows + * about it any more. + *

+ *

+ * The loaded flag of the chunk is deliberately set outside the lock, because it calls a hook a + * subclass may override, and foreign code has no business running while a position is held. The + * packet, the event, the entities and the loader follow outside for the same reason: all four can + * call back into the instance, and holding a position while foreign code runs is how two chunks + * deadlock each other. + *

+ *

+ * This type is experimental. The instance module is new and its API may still change. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ApiStatus.Experimental +public final class ChunkLifecycle { + + /** + * The instance whose chunks these are, needed for the events and for the chunk supplier. + */ + private final FalcoInstance owner; + + /** + * Where a chunk goes when it is published and where it is taken from when it is unloaded. + */ + private final ChunkRegistry registry; + + /** + * Where a chunk is read from and where its removal is reported to. + */ + private final ChunkPersistence persistence; + + /** + * What fills a chunk no loader knows about. + */ + private final ChunkGeneration generation; + + /** + * What produces the chunk objects of this instance. + */ + private volatile ChunkSupplier chunkSupplier = FalcoChunk::new; + + /** + * Whether a chunk which is asked for is loaded on demand. + */ + private volatile boolean autoChunkLoad = true; + + // retrieve(int, int) <- FalcoInstance#retrieveChunk:544 + // completeLoad(long, int, int, ChunkLoader, ...) <- FalcoInstance#completeLoad:590 + // publish(long, FalcoChunk, CompletableFuture) <- FalcoInstance#publishChunk:638 + // create(int, int) <- FalcoInstance#createChunk:662 + // unload(Chunk) <- FalcoInstance#unloadChunk:722 + // discard(long) <- FalcoInstance#discardRunningLoad:325 +} +``` + +The four methods whose bodies change, in full: + +```java + /** + * Reads a chunk through the loader, publishes it and completes the waiting future. + *

+ * The chunk is produced first and published second, and the publish may be refused. Everything in + * between the two is the window in which an unload can decide that this chunk is not wanted any + * more; a load which is refused therefore has to undo itself rather than complain. + *

+ *

+ * The loader which is told about the discard is the current one and not the one this + * load read from. The two can differ if the loader was swapped while a load was running. That is + * the behaviour this method had before the split and it is preserved rather than corrected, + * because a refactoring which changes behaviour cannot be checked by the tests that passed before + * it. + *

+ * + * @param index the chunk index of the position, the key in the registry + * @param chunkX the chunk X + * @param chunkZ the chunk Z + * @param loader the loader the chunk is read from + * @param future the future handed to the callers waiting for this chunk + */ + public void completeLoad(long index, int chunkX, int chunkZ, ChunkLoader loader, + CompletableFuture future) { + final FalcoChunk falcoChunk; + try { + Chunk chunk = loader.loadChunk(this.owner, chunkX, chunkZ); + if (chunk == null) { + chunk = create(chunkX, chunkZ); + chunk.onGenerate(); + } + falcoChunk = FalcoChunk.require(chunk); + } catch (Throwable throwable) { + this.registry.release(index, future); + future.completeExceptionally(throwable); + return; + } + if (!publish(index, falcoChunk, future)) { + // The chunk was never part of this instance, so there is no registry entry and no + // partition to clean up. The loader is still told, because it created the chunk and may + // hold bookkeeping for it, which its own documentation allows for explicitly. + falcoChunk.markUnloaded(); + this.persistence.unloaded(falcoChunk); + future.completeExceptionally(new FalcoInstanceException("the chunk " + chunkX + ":" + chunkZ + + " was unloaded while it was being loaded, so the loaded chunk was discarded")); + return; + } + falcoChunk.markLoaded(); + future.complete(falcoChunk); + EventDispatcher.call(new InstanceChunkLoadEvent(this.owner, falcoChunk)); + } + + /** + * Makes a freshly built chunk part of this instance, unless somebody claimed its position. + * + * @param index the chunk index of the position + * @param chunk the chunk to publish + * @param future the future of this load, which has to still be the entry of the position + * @return true if the chunk is now part of this instance, false if the load was claimed + */ + public boolean publish(long index, FalcoChunk chunk, CompletableFuture future) { + return this.registry.publish(index, chunk, future, + published -> MinecraftServer.process().dispatcher().createPartition(published)); + } + + /** + * Creates a chunk through the chunk supplier of this instance and fills it. + *

+ * This is the path a chunk takes which no {@link ChunkLoader} knows about. Without a generator the + * chunk stays empty, which is a world made of air rather than a failure. + *

+ * + * @param chunkX the chunk X + * @param chunkZ the chunk Z + * @return the created chunk + * @throws FalcoInstanceException if the chunk supplier returned null or a foreign chunk type + */ + public FalcoChunk create(int chunkX, int chunkZ) { + final Chunk chunk = this.chunkSupplier.createChunk(this.owner, chunkX, chunkZ); + if (chunk == null) { + throw new FalcoInstanceException("the chunk supplier returned null for chunk " + chunkX + ":" + chunkZ); + } + final FalcoChunk falcoChunk = FalcoChunk.require(chunk); + final var current = this.generation.generator(); + + if (current != null && falcoChunk.shouldGenerate()) { + this.generation.apply(falcoChunk, current); + this.owner.refreshLastBlockChangeTime(); + } else { + this.generation.applyPending(falcoChunk); + } + return falcoChunk; + } + + /** + * Removes a chunk from this instance. + * + * @param chunk the chunk to remove, has to be a {@link FalcoChunk} + * @throws FalcoInstanceException if the chunk is not a {@link FalcoChunk} + */ + public void unload(Chunk chunk) { + if (!chunk.isLoaded()) return; + final FalcoChunk falcoChunk = FalcoChunk.require(chunk); + final int chunkX = falcoChunk.getChunkX(); + final int chunkZ = falcoChunk.getChunkZ(); + final long index = CoordConversion.chunkIndex(chunkX, chunkZ); + final boolean removed = this.registry.remove(index, falcoChunk, unloaded -> { + unloaded.markUnloaded(); + MinecraftServer.process().dispatcher().deletePartition(unloaded); + }); + + if (!removed) return; + falcoChunk.sendPacketToViewers(new UnloadChunkPacket(chunkX, chunkZ)); + EventDispatcher.call(new InstanceChunkUnloadEvent(this.owner, falcoChunk)); + this.owner.getEntityTracker().chunkEntities(chunkX, chunkZ, EntityTracker.Target.ENTITIES) + .forEach(Entity::remove); + this.persistence.unloaded(falcoChunk); + } +``` + +Note the one behaviour change in `create`: `FalcoChunk.require` now runs at creation rather than at the first use of the chunk. `FalcoInstanceTest#testAForeignChunkSupplierIsRejected` still passes — it asserts that a foreign supplier is refused, not where — and the failure now names the supplier at the moment it was used instead of one step later. The `ChunkLifecycleTest` case above pins the new position. + +- [ ] **Step 5: Point `FalcoInstance` at it** + +Delete `chunkSupplier:211`, `autoChunkLoad:215`, `createChunk:662`, `requireFalcoChunk:690`, `publishChunk:638`, `completeLoad:590`, `retrieveChunk:544`, `discardRunningLoad:325` and the body of `unloadChunk:722`. Add `private final ChunkLifecycle lifecycle;` and the two accessors the tests use: + +```java + /** + * Hands out the registry of chunk positions of this instance. + *

+ * Exposed because a facade whose parts cannot be reached is a facade whose parts cannot be + * tested, which is the whole reason this class was split. + *

+ * + * @return the registry of this instance + * @since 0.4.0 + */ + public ChunkRegistry registry() { + return this.registry; + } + + /** + * Hands out the lifecycle of the chunks of this instance. + * + * @return the lifecycle of this instance + * @since 0.4.0 + */ + public ChunkLifecycle lifecycle() { + return this.lifecycle; + } +``` + +and the delegations: + +```java + @Override + public CompletableFuture loadChunk(int chunkX, int chunkZ) { + return this.lifecycle.retrieve(chunkX, chunkZ); + } + + @Override + public CompletableFuture<@Nullable Chunk> loadOptionalChunk(int chunkX, int chunkZ) { + final Chunk loaded = getChunk(chunkX, chunkZ); + if (loaded != null) return CompletableFuture.completedFuture(loaded); + if (!this.lifecycle.autoLoad()) return CompletableFuture.completedFuture(null); + return this.lifecycle.retrieve(chunkX, chunkZ); + } + + @Override + public void unloadChunk(Chunk chunk) { + this.lifecycle.unload(chunk); + } + + @Override + public void setChunkSupplier(ChunkSupplier chunkSupplier) { + this.lifecycle.supplier(chunkSupplier); + } + + @Override + public ChunkSupplier getChunkSupplier() { + return this.lifecycle.supplier(); + } + + @Override + public void enableAutoChunkLoad(boolean enable) { + this.lifecycle.autoLoad(enable); + } + + @Override + public boolean hasEnabledAutoChunkLoad() { + return this.lifecycle.autoLoad(); + } +``` + +`unregister` calls `this.lifecycle.discard(index)` and `this.lifecycle.unload(chunk)`. + +- [ ] **Step 6: Run the tests** + +```bash +./gradlew :falco-instance:test --tests "*ChunkLifecycleTest*" +./gradlew :falco-instance:test +``` + +Expected: PASS, seven and then 172. `FalcoInstanceLoadRaceTest` and `FalcoInstanceUnloadTest` are the net. + +- [ ] **Step 7: Prove the seam is real and not decorative** + +Delete the line `if (running != future) return running;` from `ChunkRegistry#publish` and watch `ChunkLifecycleTest#testPublishIsRefusedAfterADiscard` fail deterministically, in one thread, in milliseconds. Then restore it and delete it again while running only `FalcoInstanceLoadRaceTest`: that suite may well stay green, because it has to hit a window by luck. **That difference is US-3.02 and it should be written into the commit message.** + +- [ ] **Step 8: Commit** + +```bash +git add falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkLifecycle.java \ + falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoChunk.java \ + falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoInstance.java \ + falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkLifecycleTest.java +git commit -m "refactor(instance): make publish and load completion reachable one at a time" +``` + +--- + +### Task 6: `BlockWriter` + +**Files:** +- Create: `falco-instance/src/main/java/net/onelitefeather/falco/instance/BlockWriter.java` +- Modify: `falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoInstance.java` +- Test: `falco-instance/src/test/java/net/onelitefeather/falco/instance/BlockWriterTest.java` + +**Interfaces:** +- Consumes: `FalcoChunk#require(Chunk)` from Task 5, `ChunkLifecycle#autoLoad()`. +- Produces: + - `BlockWriter(FalcoInstance owner)` + - `void setBlock(int x, int y, int z, Block block, boolean doBlockUpdates)` + - `boolean placeBlock(BlockHandler.Placement placement, boolean doBlockUpdates)` + - `boolean breakBlock(Player player, Point blockPosition, BlockFace blockFace, boolean doBlockUpdates)` + - `void write(FalcoChunk chunk, int x, int y, int z, Block block, @Nullable BlockHandler.Placement placement, @Nullable BlockHandler.Destroy destroy, boolean doBlockUpdates, int updateDistance)` + - `long lastChangeTime()` + - `void refreshLastChangeTime()` + - `void endTick()` + +**Reference:** `FalcoInstance#setBlock:338`, `#placeBlock:352`, `#breakBlock:362`, `#writeBlock:413`, `#placementState:462`, `#updateNeighbours:480`, the fields `currentlyChangingBlocks:209` and `lastBlockChangeTime:217`, and `#tick:1267`. Every body moves unchanged; `getChunkAt`, `getCachedDimensionType`, `getBlock` and `loadChunk` are reached through the owner. + +**NFR-006 is the reason to read this before moving it.** The write lock of the touched chunk is held across the write and nothing else: the neighbour pass, the packets and the event all run after it was released. That ordering is the difference to `InstanceContainer`, which holds a monitor over the whole instance across all three and across arbitrary `BlockHandler` code. A move that puts the `unlockWriteLock()` one line later has undone the stage-1 measurement without failing a single test today, which is why Task 1 wrote `testANeighbourReshapesItself` first: a neighbour in another chunk taking a second chunk lock while the first is held is a deadlock, and that case now runs. + +- [ ] **Step 1: Write the failing test** + +```java +package net.onelitefeather.falco.instance; + +import net.minestom.server.instance.block.Block; +import net.minestom.server.world.DimensionType; +import net.minestom.testing.Env; +import net.minestom.testing.extension.MicrotusExtension; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; + +import java.util.UUID; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNotEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Drives the block writer of a Falco instance directly. + *

+ * Two properties are asserted here that cannot be asserted through the instance: that a write into a + * chunk which is handed in never consults the registry at all, and that the write lock of that chunk + * is not held any more once the write returned. The second is what NFR-006 is about and it used to be + * unobservable, because the only entry point took the lock, wrote, released it and ran three more + * things, all inside one {@code private} method. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ExtendWith(MicrotusExtension.class) +@DisplayName("The block writer of a Falco instance") +class BlockWriterTest { + + /** + * The height every case writes at. + */ + private static final int Y = 64; + + /** + * Creates a registered instance in the environment of the test. + * + * @param env the environment which provides the server process + * @return the registered instance + */ + private static FalcoInstance registered(Env env) { + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + return instance; + } + + @Test + @DisplayName("writes into the chunk it was handed, without asking where that chunk is") + void testWriteIntoAChunkThatIsNotInTheRegistry(Env env) { + final FalcoInstance instance = registered(env); + final BlockWriter writer = instance.blockWriter(); + final FalcoChunk orphan = new FalcoChunk(instance, 9, 9); + + writer.write(orphan, 144, Y, 144, Block.STONE, null, null, false, 0); + + orphan.lockReadLock(); + try { + assertEquals(Block.STONE, orphan.getBlock(144, Y, 144)); + } finally { + orphan.unlockReadLock(); + } + assertTrue(instance.getChunks().isEmpty(), "the writer must not have published anything"); + } + + @Test + @DisplayName("holds the write lock of the chunk only while it writes") + void testTheChunkLockIsReleased(Env env) { + final FalcoInstance instance = registered(env); + final BlockWriter writer = instance.blockWriter(); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + + writer.write(chunk, 0, Y, 0, Block.STONE, null, null, false, 0); + + // A write lock that was not released cannot be taken again from another thread, and a read + // lock cannot be taken on top of a write lock held by this one. + chunk.lockWriteLock(); + chunk.unlockWriteLock(); + } + + @Test + @DisplayName("refuses to write outside the world and says so instead of throwing") + void testAWriteOutsideTheWorldIsRefused(Env env) { + final FalcoInstance instance = registered(env); + final BlockWriter writer = instance.blockWriter(); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + + writer.write(chunk, 0, 5000, 0, Block.STONE, null, null, false, 0); + + chunk.lockReadLock(); + try { + assertEquals(Block.AIR, chunk.getBlock(0, Y, 0), "nothing may have been written anywhere"); + } finally { + chunk.unlockReadLock(); + } + } + + @Test + @DisplayName("moves its own timestamp and clears its own guard") + void testTheTimestampAndTheGuard(Env env) { + final FalcoInstance instance = registered(env); + final BlockWriter writer = instance.blockWriter(); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + final long before = writer.lastChangeTime(); + + writer.write(chunk, 0, Y, 0, Block.STONE, null, null, false, 0); + assertNotEquals(before, writer.lastChangeTime()); + + writer.endTick(); + writer.write(chunk, 0, Y, 0, Block.STONE, null, null, false, 0); + chunk.lockReadLock(); + try { + assertEquals(Block.STONE, chunk.getBlock(0, Y, 0)); + } finally { + chunk.unlockReadLock(); + } + } +} +``` + +- [ ] **Step 2: Run it and watch it fail** + +```bash +./gradlew :falco-instance:test --tests "*BlockWriterTest*" +``` + +Expected: compilation failure — `BlockWriter` and `FalcoInstance#blockWriter()` do not exist. + +- [ ] **Step 3: Write the part and point `FalcoInstance` at it** + +`BlockWriter` holds `private final FalcoInstance owner;`, `private final Map currentlyChangingBlocks = new ConcurrentHashMap<>();` and `private volatile long lastBlockChangeTime = System.nanoTime();`. The six method bodies move from the lines named above, with `this` replaced by `this.owner` wherever the instance is meant — in `new ChunkCache(this.owner, null, null)`, in `new BlockPlacementRule.PlacementState(this.owner, …)`, in `new InstanceBlockUpdateEvent(this.owner, …)` and in `new BlockHandler.PlayerDestroy(…, this.owner, …)` — and `requireFalcoChunk(chunk)` replaced by `FalcoChunk.require(chunk)`. The class javadoc takes over the paragraph of `writeBlock:394-400` about why only the chunk lock is held, because that paragraph is the reason this class exists as a separate thing at all. + +`endTick()` is `this.currentlyChangingBlocks.clear();` with the javadoc from `FalcoInstance#tick:1254-1266` about the recursion guard being scoped to a single tick. + +In `FalcoInstance`, the five delegations: + +```java + @Override + public void setBlock(int x, int y, int z, Block block, boolean doBlockUpdates) { + this.blockWriter.setBlock(x, y, z, block, doBlockUpdates); + } + + @Override + public boolean placeBlock(BlockHandler.Placement placement, boolean doBlockUpdates) { + return this.blockWriter.placeBlock(placement, doBlockUpdates); + } + + @Override + public boolean breakBlock(Player player, Point blockPosition, BlockFace blockFace, boolean doBlockUpdates) { + return this.blockWriter.breakBlock(player, blockPosition, blockFace, doBlockUpdates); + } + + public long getLastBlockChangeTime() { + return this.blockWriter.lastChangeTime(); + } + + public void refreshLastBlockChangeTime() { + this.blockWriter.refreshLastChangeTime(); + } + + @Override + public void tick(long time) { + super.tick(time); + this.blockWriter.endTick(); + } +``` + +plus `public BlockWriter blockWriter()` next to `registry()` and `lifecycle()`. + +- [ ] **Step 4: Run everything** + +```bash +./gradlew :falco-instance:test +``` + +Expected: PASS, 176. `FalcoInstanceBlockWriteTest` from Task 1 is the net and every one of its ten cases has to stay green. + +- [ ] **Step 5: Prove the lock discipline survived** + +Move `chunk.unlockWriteLock()` from the `finally` block to the end of `write`, so the lock is held across the neighbour pass. `BlockWriterTest#testTheChunkLockIsReleased` fails; `FalcoInstanceBlockWriteTest#testANeighbourReshapesItself` fails or hangs. Restore it. Before this stage neither existed, and the change would have been invisible. + +- [ ] **Step 6: Commit** + +```bash +git add falco-instance/src/main/java/net/onelitefeather/falco/instance/BlockWriter.java \ + falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoInstance.java \ + falco-instance/src/test/java/net/onelitefeather/falco/instance/BlockWriterTest.java +git commit -m "refactor(instance): give the block write path a class of its own" +``` + +--- + +### Task 7: The facade holds no state + +**Files:** +- Modify: `falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoInstance.java` +- Test: `falco-instance/src/test/java/net/onelitefeather/falco/instance/InstanceFacadeTest.java` + +**Interfaces:** +- Consumes: the four parts of Tasks 2, 3, 5 and 6, plus `ChunkGeneration` from Task 4. +- Produces: `FalcoInstance` with exactly four declared instance fields, and nothing else. + +**Why this is a task and not a review note.** §8 of the spec lists it as the open question of this stage: *whether the facade split can stay thin, or whether it re-accumulates state, can only be judged once written.* A judgement nobody can repeat is not an answer. This task turns it into an assertion that runs on every build. + +**The one field that has to go.** After Task 6, `FalcoInstance` still declares `registries:195` — handed to `ChunkGeneration` in the constructor and never read again. It is deleted; the constructor passes its parameter straight through. `ChunkGeneration` is reached through `ChunkLifecycle`, which is the only thing that generates, so it is not a fifth field of the facade: `ChunkLifecycle` holds it. + +- [ ] **Step 1: Write the failing test** + +```java +package net.onelitefeather.falco.instance; + +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +import java.lang.reflect.Field; +import java.lang.reflect.Modifier; +import java.util.List; +import java.util.Set; +import java.util.stream.Collectors; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Asserts that {@link FalcoInstance} is a facade and not the class it replaced with delegation in + * front of it. + *

+ * §4.3 of the design says it in one sentence: the facade must hold no state of its own, or it is + * the same class with delegation in front of it. §8 lists whether that holds as the open question + * of this stage. A question that can only be answered by a person reading the file is answered again + * every time somebody reads it, and differently; this class answers it once per build. + *

+ * + *

Why this is reflection, and why that is allowed here

+ *

+ * NFR-001 forbids reflection in the modules, so that they run without {@code --add-opens} and without + * an open module. It says nothing about a test, and this repository already reads private fields of a + * foreign library in {@code JolMeasurement} for a reason of the same shape: the property being + * checked is a property of the declaration, and nothing but the declaration can be asked about it. + * The alternative — a JOL walk of the shallow size — was rejected because it cannot tell a fifth + * reference field from padding, which is exactly the blind spot the stage 2 result had to write down + * about {@code ChunkFootprintTest}. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@DisplayName("The instance facade") +class InstanceFacadeTest { + + /** + * The four types a field of the facade is allowed to have. + */ + private static final Set> PARTS = Set.of( + ChunkRegistry.class, ChunkLifecycle.class, BlockWriter.class, ChunkPersistence.class); + + /** + * Returns every instance field the facade declares itself, ignoring what it inherits. + * + * @return the declared, non-static fields of the facade + */ + private static List declaredFields() { + return java.util.Arrays.stream(FalcoInstance.class.getDeclaredFields()) + .filter(field -> !Modifier.isStatic(field.getModifiers())) + .filter(field -> !field.isSynthetic()) + .toList(); + } + + @Test + @DisplayName("declares exactly the four parts it delegates to") + void testTheFacadeDeclaresOnlyItsParts() { + final List fields = declaredFields(); + final String names = fields.stream() + .map(field -> field.getType().getSimpleName() + " " + field.getName()) + .collect(Collectors.joining(", ")); + + assertEquals(PARTS.size(), fields.size(), + "the facade may hold one reference per part and nothing else, but it declares: " + names); + for (Field field : fields) { + assertTrue(PARTS.contains(field.getType()), + "the facade declares a field of type " + field.getType().getName() + " named " + + field.getName() + ", which is state of its own rather than a part; either it " + + "belongs in one of " + PARTS + " or the split of stage 3 has been undone"); + } + assertEquals(PARTS, + fields.stream().map(Field::getType).collect(Collectors.toUnmodifiableSet()), + "every part has to be reachable from the facade, and each exactly once"); + } + + @Test + @DisplayName("declares every one of them final") + void testTheFacadeCannotSwapItsParts() { + for (Field field : declaredFields()) { + assertTrue(Modifier.isFinal(field.getModifiers()), + "the field " + field.getName() + " is not final; a part that can be replaced at " + + "runtime is a part two threads can disagree about"); + } + } +} +``` + +- [ ] **Step 2: Run it and watch it fail** + +```bash +./gradlew :falco-instance:test --tests "*InstanceFacadeTest*" +``` + +Expected: **failure naming `Registries registries`** — the field Task 4 left behind. That failure is the test doing its job on its first run, which is worth more than a green one. + +- [ ] **Step 3: Delete the field** + +Remove `registries:195` from `FalcoInstance` and hand the constructor parameter straight to `new ChunkGeneration(registries, this::getChunkAt)`. The constructor ends as: + +```java + public FalcoInstance(Registries registries, UUID uuid, RegistryKey dimensionType, + @Nullable ChunkLoader loader, Key dimensionName) { + super(registries, uuid, dimensionType, dimensionName); + this.registry = new ChunkRegistry(); + this.persistence = new ChunkPersistence(loader); + this.blockWriter = new BlockWriter(this); + this.lifecycle = new ChunkLifecycle(this, this.registry, this.persistence, + new ChunkGeneration(registries, this::getChunkAt)); + // Last, and outside every constructor above: loadInstance may call back into this instance, + // and a callback into an object whose parts are not all built yet reads one of them as null. + this.persistence.loader().loadInstance(this); + } +``` + +`lastBlockChangeTime` was initialised here before and now lives in `BlockWriter`'s field initialiser, which is the same value at a slightly earlier moment and is only ever read as a delta. + +- [ ] **Step 4: Rewrite the class javadoc of `FalcoInstance`** + +The current one describes a class that does the work. It now describes a facade, and it has to say four things: what the four parts are and where the line between them runs; that the class holds nothing else and that `InstanceFacadeTest` is what keeps that true; that the four `instanceof InstanceContainer` branches of Minestom still apply unchanged; and that `unregister(InstanceManager)` is still the reason the class exists. Everything the old comment says about the chunk lock, the generator staging and the publish/unload exclusivity moves to the part that now owns it — that is not a deletion, it is the comment following its code. Raise `@version` to `2.0.0`: the constructor is unchanged but `getChunkLoader`, `setChunkLoader` and every accessor now delegate, and three new public accessors exist. + +- [ ] **Step 5: Run everything** + +```bash +./gradlew :falco-instance:test +./gradlew :falco-instance:javadoc +``` + +Expected: PASS, 178, and a javadoc run without a single warning — `-Werror` is on and every new public member of Tasks 2 to 6 is public API now. + +- [ ] **Step 6: Prove the assertion bites** + +Add `private final Map shortcut = new ConcurrentHashMap<>();` to `FalcoInstance`, run `InstanceFacadeTest`, and see it fail by name and by type. Then make one of the four fields non-final and see the second case fail. Remove both. A structural test that nobody has watched fail is a structural test nobody knows the shape of. + +- [ ] **Step 7: Record the line count** + +```bash +wc -l falco-instance/src/main/java/net/onelitefeather/falco/instance/*.java +``` + +Write the numbers into the commit message. The stage began with one file of 1 272 lines; the point is not that the total shrinks — it will not, because every new type carries its own javadoc — but that no single file is the place where five responsibilities meet. + +- [ ] **Step 8: Commit** + +```bash +git add falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoInstance.java \ + falco-instance/src/test/java/net/onelitefeather/falco/instance/InstanceFacadeTest.java +git commit -m "refactor(instance)!: make the instance a facade and assert that it stays one" +``` + +--- + +### Task 8: `ChunkLifecycleListener` — US-3.03 and US-3.04 + +**Files:** +- Create: `falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkLifecycleListener.java` +- Create: `falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkLifecycleEvent.java` +- Modify: `falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoChunk.java` +- Modify: `falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkLifecycle.java` +- Test: `falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkLifecycleListenerTest.java` +- Test: `falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkLifecycleAllocationTest.java` +- Modify: `falco-benchmarks/src/test/java/net/onelitefeather/falco/benchmark/instance/ChunkFootprintTest.java` + +**Interfaces:** +- Consumes: `FalcoChunk`, `ChunkLifecycle` as Tasks 5 and 7 left them. +- Produces: + - `interface ChunkLifecycleListener` with `default void onLoad(ChunkLifecycleEvent)`, `onPublish(ChunkLifecycleEvent)`, `onTick(ChunkLifecycleEvent)`, `onUnload(ChunkLifecycleEvent)`, `default void onBlockChange(FalcoChunk chunk, int x, int y, int z, Block block)`, and `static ChunkLifecycleListener of(ChunkLifecycleListener first, ChunkLifecycleListener second)` + - `record ChunkLifecycleEvent(FalcoChunk chunk, long time)` + - `FalcoChunk#addLifecycleListener(ChunkLifecycleListener)`, `FalcoChunk#lifecycleListener()`, `FalcoChunk#notifyPublished()` + - `ChunkLifecycle#addListener(ChunkLifecycleListener)`, `ChunkLifecycle#listener()` + + Task 10 depends on all of them. + +**The correction this task makes to the design.** §4.5 names four hooks, `onLoad`, `onPublish`, `onTick` and `onUnload`, and says they replace the four `FalcoLightingChunk` occupies by inheritance. Reading `FalcoLightingChunk` shows five overrides, not four: `setBlock`, `onLoad`, `tick`, `invalidate` and `onLightUpdated`. Two of them are not lifecycle transitions at all. + +- `setBlock` is where light learns *which block* moved, and that is the difference between replaying one position and searching nine chunks — `FalcoLightingChunk:128` hands the coordinates to `markChanged`. It becomes a fifth listener method, `onBlockChange`, and it takes primitives rather than an event, because it runs once per block write and an event per write would be an allocation on the hottest path this module has. +- `invalidate` and `onLightUpdated` need per-chunk state — a `CachedPacket` — and a listener registered once for a whole instance has nowhere to put it. They stay on the chunk class, which Task 10 keeps for exactly that reason. + +The listener is therefore five methods, four of which carry an event and one of which does not, and the asymmetry is the measurement talking rather than taste. + +**Why a single nullable reference and not a list.** A `List` costs an object per chunk whether or not anybody listens, and an enhanced-for over it allocates an iterator per transition. One reference field costs four bytes and composes through `of`, which nests two listeners into one and allocates once, at registration. `FalcoChunk` is the class stage 2 got down to 25 objects and 840 bytes; a list per chunk would give a quarter of that back for a feature almost no chunk uses. + +- [ ] **Step 1: Write the failing tests** + +`ChunkLifecycleListenerTest` — US-3.03: + +```java +package net.onelitefeather.falco.instance; + +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.block.Block; +import net.minestom.server.world.DimensionType; +import net.minestom.testing.Env; +import net.minestom.testing.extension.MicrotusExtension; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; + +import java.util.ArrayList; +import java.util.List; +import java.util.UUID; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertSame; + +/** + * Establishes that a chunk can carry more than one lifecycle extension, which is US-3.03. + *

+ * Before this stage a chunk had exactly one extension point and it was its superclass, so + * {@code FalcoLightingChunk} occupied it and nothing else could be installed beside light. Two + * listeners on one chunk, both notified on every transition, is the shape that removes that limit. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ExtendWith(MicrotusExtension.class) +@DisplayName("The lifecycle listeners of a chunk") +class ChunkLifecycleListenerTest { + + /** + * A listener which writes down what it was told, in order. + */ + private static final class Recording implements ChunkLifecycleListener { + + /** + * The name this listener writes in front of every entry. + */ + private final String name; + + /** + * Where the entries go. + */ + private final List log; + + /** + * Creates a recording listener. + * + * @param name the name of this listener + * @param log where the entries go + */ + private Recording(String name, List log) { + this.name = name; + this.log = log; + } + + @Override + public void onPublish(ChunkLifecycleEvent event) { + this.log.add(this.name + ":publish:" + event.chunk().getChunkX()); + } + + @Override + public void onLoad(ChunkLifecycleEvent event) { + this.log.add(this.name + ":load"); + } + + @Override + public void onTick(ChunkLifecycleEvent event) { + this.log.add(this.name + ":tick:" + event.time()); + } + + @Override + public void onUnload(ChunkLifecycleEvent event) { + this.log.add(this.name + ":unload"); + } + + @Override + public void onBlockChange(FalcoChunk chunk, int x, int y, int z, Block block) { + this.log.add(this.name + ":block:" + x + "/" + y + "/" + z); + } + } + + /** + * Creates a registered instance in the environment of the test. + * + * @param env the environment which provides the server process + * @return the registered instance + */ + private static FalcoInstance registered(Env env) { + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + return instance; + } + + @Test + @DisplayName("notifies both listeners on every transition, in registration order") + void testTwoListenersBothHearEverything(Env env) { + final FalcoInstance instance = registered(env); + final List log = new ArrayList<>(); + instance.lifecycle().addListener(new Recording("first", log)); + instance.lifecycle().addListener(new Recording("second", log)); + + final Chunk chunk = instance.loadChunk(0, 0).join(); + chunk.lockWriteLock(); + try { + FalcoChunk.require(chunk).setBlock(1, 64, 1, Block.STONE, null, null); + } finally { + chunk.unlockWriteLock(); + } + chunk.tick(7L); + instance.unloadChunk(chunk); + + assertEquals(List.of( + "first:publish:0", "second:publish:0", + "first:load", "second:load", + "first:block:1/64/1", "second:block:1/64/1", + "first:tick:7", "second:tick:7", + "first:unload", "second:unload"), log); + } + + @Test + @DisplayName("holds no listener until one is registered") + void testAChunkStartsWithoutAListener(Env env) { + final FalcoInstance instance = registered(env); + + assertNull(new FalcoChunk(instance, 0, 0).lifecycleListener(), + "a chunk nobody listens to has to hold null, not an empty composite"); + assertNull(instance.lifecycle().listener()); + } + + @Test + @DisplayName("keeps the single listener single when there is only one") + void testOneListenerIsNotWrapped(Env env) { + final FalcoInstance instance = registered(env); + final ChunkLifecycleListener only = new Recording("only", new ArrayList<>()); + + instance.lifecycle().addListener(only); + + assertSame(only, instance.lifecycle().listener(), + "one listener composes with nothing, so it has to be stored as it is"); + } + + @Test + @DisplayName("gives a chunk of a plain container a listener too") + void testAChunkCanCarryItsOwnListener(Env env) { + final FalcoInstance instance = registered(env); + final List log = new ArrayList<>(); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + + chunk.addLifecycleListener(new Recording("own", log)); + chunk.tick(3L); + + assertEquals(List.of("own:tick:3"), log, + "the listener lives on the chunk, so a chunk outside a Falco instance can carry one"); + } +} +``` + +`ChunkLifecycleAllocationTest` — US-3.04, and the whole point of it is that it measures both arms: + +```java +package net.onelitefeather.falco.instance; + +import com.sun.management.ThreadMXBean; +import net.minestom.server.world.DimensionType; +import net.minestom.testing.Env; +import net.minestom.testing.extension.MicrotusExtension; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; + +import java.lang.management.ManagementFactory; +import java.util.UUID; + +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.junit.jupiter.api.Assumptions.assumeTrue; + +/** + * Counts what a lifecycle transition allocates, with no listener and with one, which is US-3.04. + *

+ * The requirement is that a chunk nobody listens to pays nothing per transition. That is a claim + * about an allocation, and an allocation is measured rather than argued: the two arms below run the + * identical loop and differ only in whether a listener is installed, and the difference between them + * is the cost of the event. + *

+ * + *

Why the listener arm has to publish the event

+ *

+ * A test which only measured the null arm would pass against an implementation that allocates an + * event on every transition, as long as escape analysis noticed that nothing escaped and deleted the + * allocation. The listener below therefore writes the event into a {@code static volatile} field, + * which no compiler may remove, so the second arm is a positive control: if it does not allocate, the + * measurement itself is broken and the first arm proves nothing. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ExtendWith(MicrotusExtension.class) +@DisplayName("What a lifecycle transition allocates") +class ChunkLifecycleAllocationTest { + + /** + * How many transitions each arm performs. + */ + private static final int TRANSITIONS = 200_000; + + /** + * How many transitions are run before the measurement, so both arms are compiled. + */ + private static final int WARMUP = 50_000; + + /** + * Where the listener arm publishes its events, so that nothing can be optimised away. + */ + private static volatile Object sink; + + /** + * Ticks a chunk the given number of times and reports what the calling thread allocated. + * + * @param chunk the chunk to tick + * @param times how often to tick it + * @return the bytes the calling thread allocated during the loop + */ + private static long allocatedWhileTicking(FalcoChunk chunk, int times) { + final ThreadMXBean threads = (ThreadMXBean) ManagementFactory.getThreadMXBean(); + final long before = threads.getCurrentThreadAllocatedBytes(); + + for (int index = 0; index < times; index++) { + chunk.tick(index); + } + return threads.getCurrentThreadAllocatedBytes() - before; + } + + @Test + @DisplayName("costs nothing without a listener and one event with one") + void testTheEventIsBuiltOnlyWhenSomebodyListens(Env env) { + final ThreadMXBean threads = (ThreadMXBean) ManagementFactory.getThreadMXBean(); + assumeTrue(threads.isThreadAllocatedMemorySupported(), + "this JVM cannot report per thread allocation, so the question cannot be answered here"); + threads.setThreadAllocatedMemoryEnabled(true); + + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + final FalcoChunk silent = new FalcoChunk(instance, 0, 0); + final FalcoChunk heard = new FalcoChunk(instance, 1, 0); + heard.addLifecycleListener(new ChunkLifecycleListener() { + + @Override + public void onTick(ChunkLifecycleEvent event) { + sink = event; + } + }); + + allocatedWhileTicking(silent, WARMUP); + allocatedWhileTicking(heard, WARMUP); + final long withoutListener = allocatedWhileTicking(silent, TRANSITIONS); + final long withListener = allocatedWhileTicking(heard, TRANSITIONS); + + System.out.printf("lifecycle transitions: %,d without a listener -> %,d B (%.3f B each)%n", + TRANSITIONS, withoutListener, (double) withoutListener / TRANSITIONS); + System.out.printf("lifecycle transitions: %,d with one listener -> %,d B (%.3f B each)%n", + TRANSITIONS, withListener, (double) withListener / TRANSITIONS); + + assertTrue(withListener >= 16L * TRANSITIONS, + "the positive control failed: a listener that stores its event has to allocate one per " + + "transition, but the arm with a listener allocated " + withListener + + " B over " + TRANSITIONS + " transitions, so this measurement cannot see " + + "allocations at all and its other half proves nothing"); + assertTrue(withoutListener < TRANSITIONS, + "a chunk nobody listens to allocated " + withoutListener + " B over " + TRANSITIONS + + " transitions, which is more than a byte each: the event is being built before " + + "the listener is checked"); + } +} +``` + +- [ ] **Step 2: Run both and watch them fail** + +```bash +./gradlew :falco-instance:test --tests "*ChunkLifecycle*Test*" +``` + +Expected: compilation failure — neither type exists. + +- [ ] **Step 3: Write the event and the listener** + +```java +package net.onelitefeather.falco.instance; + +import org.jetbrains.annotations.ApiStatus; + +/** + * The {@link ChunkLifecycleEvent} record is what a {@link ChunkLifecycleListener} is told about a + * transition of a chunk. + *

+ * It is a record with two components rather than four method parameters because a transition will + * grow things worth reporting and a parameter list cannot. It is built by the chunk, once per + * transition, and only when a listener is installed — {@code FalcoChunk} checks the listener + * field before it constructs anything, which is what makes a chunk nobody listens to free. + * {@code ChunkLifecycleAllocationTest} measures both halves of that sentence. + *

+ *

+ * The instance is not a component: it is {@code chunk.getInstance()} and duplicating it would make + * the record wider for every transition to save one call on the few that need it. + *

+ * + * @param chunk the chunk the transition happened to + * @param time the tick time in milliseconds for {@link ChunkLifecycleListener#onTick}, and + * {@code 0} for every other transition, because the other three do not happen at a tick + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ApiStatus.Experimental +public record ChunkLifecycleEvent(FalcoChunk chunk, long time) { +} +``` + +```java +package net.onelitefeather.falco.instance; + +import net.minestom.server.instance.block.Block; +import org.jetbrains.annotations.ApiStatus; + +import java.util.Objects; + +/** + * The {@link ChunkLifecycleListener} interface is how something is told what happens to a chunk, + * without being that chunk. + *

+ * Before this interface a chunk had exactly one extension point and it was its superclass. + * {@code FalcoLightingChunk} occupied it, which is why Falco's light and Falco's instance could not + * be used together at all — {@code FalcoChunk} and {@code FalcoLightingChunk} both extended + * {@code DynamicChunk}, a class has one superclass, and a server had to pick one of the two. A + * listener is a field, and a field composes. + *

+ * + *

Why the block change is not an event

+ *

+ * Four of these five methods happen once in the life of a chunk or once per tick, and they carry a + * {@link ChunkLifecycleEvent}. {@link #onBlockChange} happens once per block written and takes + * primitives, because an event object there would be an allocation on the hottest path of this + * module. The asymmetry is deliberate and it is measured rather than argued: see + * {@code ChunkLifecycleAllocationTest}. + *

+ *

+ * Every method is a default doing nothing, so a listener implements what it cares about. Every one of + * them runs on the thread that caused the transition, under whatever lock that thread holds — a + * listener which blocks blocks a chunk load, a tick or a block write. + *

+ *

+ * This type is experimental. The instance module is new and its API may still change. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ApiStatus.Experimental +public interface ChunkLifecycleListener { + + /** + * Reports that a chunk has become part of its instance and has a tick partition. + *

+ * Fired after the position of the chunk was released and therefore outside the lock of that + * position, which is what makes it safe for a listener to call back into the instance. + *

+ * + * @param event what happened, to which chunk + */ + default void onPublish(ChunkLifecycleEvent event) { + } + + /** + * Reports that a chunk has finished loading and is now reported as loaded. + * + * @param event what happened, to which chunk + */ + default void onLoad(ChunkLifecycleEvent event) { + } + + /** + * Reports that a chunk was ticked. + *

+ * Fired on every tick of the chunk, before the block handlers of that chunk run and regardless of + * whether the chunk holds any, so a listener which needs a heartbeat gets one from every chunk + * rather than only from the ones that carry a block entity. + *

+ * + * @param event what happened, to which chunk, and at which tick time + */ + default void onTick(ChunkLifecycleEvent event) { + } + + /** + * Reports that a chunk is no longer part of its instance. + * + * @param event what happened, to which chunk + */ + default void onUnload(ChunkLifecycleEvent event) { + } + + /** + * Reports that one block of a chunk was written. + *

+ * Fired after the block is in the storage and after the handlers of the old and the new block + * ran, holding the write lock of the chunk. The position is world coordinates, as the chunk + * received them. + *

+ * + * @param chunk the chunk which received the block + * @param x the block X + * @param y the block Y + * @param z the block Z + * @param block the block which was written + */ + default void onBlockChange(FalcoChunk chunk, int x, int y, int z, Block block) { + } + + /** + * Composes two listeners into one which notifies both, in order. + *

+ * Composition rather than a list because a list is an object per chunk and an iterator per + * transition, and almost every chunk of a world has no listener at all. Two listeners nest into + * one object, three into two, and the allocation happens once, at registration. + *

+ * + * @param first the listener notified first + * @param second the listener notified second + * @return a listener which notifies both + */ + static ChunkLifecycleListener of(ChunkLifecycleListener first, ChunkLifecycleListener second) { + Objects.requireNonNull(first, "the first listener cannot be null"); + Objects.requireNonNull(second, "the second listener cannot be null"); + return new ChunkLifecycleListener() { + + @Override + public void onPublish(ChunkLifecycleEvent event) { + first.onPublish(event); + second.onPublish(event); + } + + @Override + public void onLoad(ChunkLifecycleEvent event) { + first.onLoad(event); + second.onLoad(event); + } + + @Override + public void onTick(ChunkLifecycleEvent event) { + first.onTick(event); + second.onTick(event); + } + + @Override + public void onUnload(ChunkLifecycleEvent event) { + first.onUnload(event); + second.onUnload(event); + } + + @Override + public void onBlockChange(FalcoChunk chunk, int x, int y, int z, Block block) { + first.onBlockChange(chunk, x, y, z, block); + second.onBlockChange(chunk, x, y, z, block); + } + }; + } +} +``` + +- [ ] **Step 4: Wire it into `FalcoChunk`** + +One field, one adder, one reader, and five notification points. Every one of them checks the field before it builds anything: + +```java + /** + * What is told about the transitions of this chunk, null while nobody listens. + *

+ * One reference and not a list. A list is an object per chunk and an iterator per transition, and + * a fresh chunk of this class retains 840 bytes in total — a per-chunk collection for a feature + * almost no chunk uses would give back a quarter of what stage 2 bought. More than one listener + * composes through {@link ChunkLifecycleListener#of}, which allocates once, at registration. + *

+ *

+ * Volatile because a listener may be installed by the thread that loads a chunk and read by the + * thread that ticks it. + *

+ */ + private volatile @Nullable ChunkLifecycleListener lifecycleListener; + + /** + * Adds a listener to this chunk. + * + * @param listener the listener to add + * @since 0.4.0 + */ + public void addLifecycleListener(ChunkLifecycleListener listener) { + final ChunkLifecycleListener current = this.lifecycleListener; + this.lifecycleListener = current == null ? Objects.requireNonNull(listener, + "the listener cannot be null") : ChunkLifecycleListener.of(current, listener); + } + + /** + * Hands out what is told about the transitions of this chunk. + * + * @return the listener of this chunk, or null if nothing listens + * @since 0.4.0 + */ + public @Nullable ChunkLifecycleListener lifecycleListener() { + return this.lifecycleListener; + } + + /** + * Tells the chunk that it has become part of its instance. + *

+ * Separate from {@link #markLoaded()} because publishing and finishing a load are two different + * moments: a chunk is in the registry and has a tick partition before its loaded flag is set, and + * a listener that wants to see the world exactly as the instance does needs the first, not the + * second. + *

+ * + * @since 0.4.0 + */ + public void notifyPublished() { + final ChunkLifecycleListener listener = this.lifecycleListener; + if (listener != null) listener.onPublish(new ChunkLifecycleEvent(this, 0L)); + } +``` + +`markLoaded()` and `markUnloaded()` gain the same two lines with `onLoad` and `onUnload`. `tick(long)` notifies **before** its early exit: + +```java + @Override + public void tick(long time) { + final ChunkLifecycleListener listener = this.lifecycleListener; + // Before the early exit, not after: a listener which wants a heartbeat has to get one from + // every chunk, and almost every chunk has no tickable block at all. + if (listener != null) listener.onTick(new ChunkLifecycleEvent(this, time)); + if (this.tickableCount == 0) return; + … + } +``` + +and `setBlock` ends with: + +```java + final ChunkLifecycleListener listener = this.lifecycleListener; + if (listener != null) listener.onBlockChange(this, x, y, z, block); +``` + +placed **after** the two heightmap refreshes, so a listener reading the chunk sees the finished state. + +In `ChunkLifecycle`, one field, `addListener` composing into it, and two lines: `create` calls `falcoChunk.addLifecycleListener(current)` when the lifecycle has one, and `publish` calls `chunk.notifyPublished()` after the registry returned true and released the position. + +- [ ] **Step 5: Run the two tests, then the module** + +```bash +./gradlew :falco-instance:test --tests "*ChunkLifecycle*Test*" +./gradlew :falco-instance:test +``` + +Expected: PASS. `ChunkLifecycleAllocationTest` prints two lines; the first has to be `0.000 B each` or very close to it, the second at least 16 B each. + +- [ ] **Step 6: Prove both arms of the allocation test** + +Move the event construction in `tick` in front of the null check — `final ChunkLifecycleEvent event = new ChunkLifecycleEvent(this, time); if (listener != null) listener.onTick(event);` — and watch the null arm go red with roughly 24 B per transition. Restore it. Then change the test's listener to ignore its event instead of storing it, and watch the positive control go red because escape analysis removed the allocation. Restore that too. A test that measures nothing looks exactly like a test that measured zero. + +- [ ] **Step 7: Re-measure the chunk footprint and re-declare it** + +```bash +./gradlew :falco-benchmarks:test --tests "*ChunkFootprintTest*" -i +``` + +`FalcoChunk` has one reference field more than it had. Two assertions can move: + +1. the per-class difference table, if the extra field pushed the shallow size of the chunk up; +2. `assertEquals(ClassLayout.parseInstance(minestomChunk).instanceSize(), ClassLayout.parseInstance(falcoChunk).instanceSize(), …)`, which demands that `FalcoChunk` and `DynamicChunk` weigh the same as objects. + +If either goes red, **update the declared number and write down why**, in the test's own javadoc: one reference field for the lifecycle listener, four bytes under compressed references, and what it bought. Do not widen a comparison into a tolerance — the stage 2 result already records that a `boolean` field is invisible to this test, and a tolerance would make a reference field invisible too. Raise the `@version` of `ChunkFootprintTest`. + +- [ ] **Step 8: Commit** + +```bash +git add falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkLifecycleListener.java \ + falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkLifecycleEvent.java \ + falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoChunk.java \ + falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkLifecycle.java \ + falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkLifecycleListenerTest.java \ + falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkLifecycleAllocationTest.java \ + falco-benchmarks/src/test/java/net/onelitefeather/falco/benchmark/instance/ChunkFootprintTest.java +git commit -m "feat(instance): let a chunk carry more than one lifecycle extension" +``` + +--- + +### Task 9: The viewer cache entry goes with the chunk — US-3.01 + +**Files:** +- Create: `falco-instance/src/main/java/net/minestom/server/instance/ChunkViewerCache.java` +- Modify: `falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkLifecycle.java` +- Test: `falco-instance/src/test/java/net/minestom/server/instance/ChunkViewerCacheTest.java` +- Modify: `falco-benchmarks/src/test/java/net/minestom/server/instance/ChunkViewerCacheLeakTest.java` + +**Interfaces:** +- Consumes: `EntityTrackerImpl.targetEntries`, `EntityTrackerImpl.TargetEntry#viewers`, `EntityTrackerImpl.ChunkViewKey` — all package-private members of `net.minestom.server.instance`. +- Produces: `static boolean ChunkViewerCache.release(Instance instance, int chunkX, int chunkZ)` and `static int ChunkViewerCache.size(Instance instance)`. + +**What is actually being fixed.** M14 of the spec measures an `InstanceContainer` leaking one viewer cache entry per chunk **construction**, linear and unbounded, because `InstanceContainer#getSharedInstances` hands out a fresh `unmodifiableList` every time and `ChunkViewKey#equals` compares that list by identity. A `FalcoInstance` is not an `InstanceContainer`, receives the `List.of()` singleton and therefore escapes the growth — by accident, not by design. What it does not escape is the entry itself: one per chunk position, created when the first chunk there is constructed, never removed, alive for the life of the process. `ChunkViewerCacheLeakTest` already says so in its own javadoc: *that is a far smaller quantity than one per construction, and it is not nothing.* + +**Why a class in Minestom's package.** `EntityTracker#viewable` is `computeIfAbsent` and has no counterpart; there is no public way to remove an entry. The map, its key type and `EntityTrackerImpl` itself are package-private (`EntityTrackerImpl.java:31, :252, :269`), which makes them reachable from a class declared in `net.minestom.server.instance` and from nowhere else without reflection. `ChunkViewerCacheLeakTest` has done exactly this since stage 1; this task moves the same technique from a test into the module. + +**What that costs, stated rather than discovered later.** `falco-instance.jar` then contains a package that also exists in `minestom.jar`. On the classpath — which is how every consumer of this repository runs today, and how Minestom's own test harness runs — a split package is invisible and package-private access works, because both jars land in the same runtime package of the same classloader. On the module path it is fatal: Minestom ships a `module-info.java` and two modules may not export the same package. Falco has no `module-info.java`, so this changes nothing that works today, and it closes the door on Falco ever becoming a named module without moving this class. That sentence belongs in the class comment. + +- [ ] **Step 1: Write the failing test** + +```java +package net.minestom.server.instance; + +import net.minestom.server.world.DimensionType; +import net.onelitefeather.falco.instance.FalcoInstance; +import net.minestom.testing.Env; +import net.minestom.testing.extension.MicrotusExtension; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; + +import java.util.UUID; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Establishes that a chunk which is unloaded takes its viewer cache entry with it, which is US-3.01. + *

+ * The entry is created by the constructor of {@code Chunk} ({@code Chunk.java:74-76}), which asks the + * entity tracker of the instance for a viewable and gets one out of a + * {@code computeIfAbsent}. Nothing in Minestom ever removes it: not unloading the chunk, not dropping + * the last reference to it, not unregistering the instance. A world which streams chunks in and out + * therefore accumulates one entry per position ever visited, for the life of the process. + *

+ *

+ * This test lives in {@code net.minestom.server.instance} for the same reason the class it tests + * does: the map is package-private and reading it from anywhere else would need reflection. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ExtendWith(MicrotusExtension.class) +@DisplayName("The viewer cache entry of a chunk") +class ChunkViewerCacheTest { + + /** + * Creates a registered instance in the environment of the test. + * + * @param env the environment which provides the server process + * @return the registered instance + */ + private static FalcoInstance registered(Env env) { + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + return instance; + } + + @Test + @DisplayName("is created by the chunk constructor and removed by the release") + void testTheEntryCanBeReleased(Env env) { + final FalcoInstance instance = registered(env); + final int before = ChunkViewerCache.size(instance); + + new net.onelitefeather.falco.instance.FalcoChunk(instance, 4, 4); + assertEquals(before + 1, ChunkViewerCache.size(instance), + "constructing a chunk has to leave exactly one entry behind, or this test is measuring " + + "something other than the leak it is named after"); + + assertTrue(ChunkViewerCache.release(instance, 4, 4)); + assertEquals(before, ChunkViewerCache.size(instance)); + } + + @Test + @DisplayName("reports that there was nothing to release when there was not") + void testReleasingNothing(Env env) { + final FalcoInstance instance = registered(env); + + assertFalse(ChunkViewerCache.release(instance, 77, 77), + "no chunk was ever built at that position, so no entry can be removed"); + } + + @Test + @DisplayName("leaves the cache where it found it across a load and an unload") + void testALoadAndUnloadCycleIsNeutral(Env env) { + final FalcoInstance instance = registered(env); + final int before = ChunkViewerCache.size(instance); + + for (int round = 0; round < 32; round++) { + instance.unloadChunk(instance.loadChunk(round, 0).join()); + } + + assertEquals(before, ChunkViewerCache.size(instance), + "thirty-two load and unload cycles have to leave the cache exactly as they found it"); + } +} +``` + +- [ ] **Step 2: Run it and watch it fail** + +```bash +./gradlew :falco-instance:test --tests "*ChunkViewerCacheTest*" +``` + +Expected: compilation failure — `ChunkViewerCache` does not exist. + +- [ ] **Step 3: Write the class** + +```java +package net.minestom.server.instance; + +import net.minestom.server.entity.Entity; +import org.jetbrains.annotations.ApiStatus; + +import java.util.List; + +/** + * The {@link ChunkViewerCache} class removes the viewer cache entry a chunk leaves behind, which + * Minestom offers no way to do. + *

+ * The constructor of {@code Chunk} asks the entity tracker of its instance for a {@code Viewable} + * and receives it out of a {@code computeIfAbsent} keyed by the chunk position + * ({@code Chunk.java:74-76}, {@code EntityTrackerImpl.java:207-210}). Nothing removes that entry + * again — not unloading the chunk, not dropping the last reference to it, not unregistering the + * instance — so a world which streams chunks accumulates one entry per position it has ever visited + * and keeps them until the process ends. + *

+ * + *

Why this class lives in a package of Minestom

+ *

+ * {@code EntityTracker#viewable(List, int, int)} is the only public door to that map and it only + * inserts. The map itself ({@code EntityTrackerImpl.TargetEntry#viewers}), its key type + * ({@code EntityTrackerImpl.ChunkViewKey}) and {@code EntityTrackerImpl} are all package-private, so + * a class declared in {@code net.minestom.server.instance} can reach them and nothing else can + * without reflection — which NFR-001 forbids, and which would break on the first JDK that closes the + * door. + *

+ *

+ * The price is a split package: this jar carries a package that {@code minestom.jar} also carries. On + * the classpath that is invisible and package-private access works, because both jars land in the + * same runtime package of the same classloader; on the module path it is fatal, because Minestom is a + * named module and two modules may not own one package. Falco declares no module and neither does + * anything that consumes it, so nothing that works today changes. What this does close is the option + * of Falco becoming a named module while this class stays where it is. + *

+ * + *

What it does not fix

+ *

+ * An {@code InstanceContainer} hands the tracker a fresh {@code unmodifiableList} of its shared + * instances on every chunk construction, and {@code ChunkViewKey#equals} compares that list by + * identity, so no key built here can ever match one of its entries. The unbounded growth of a + * container is not reachable from the outside and is not addressed. What is addressed is the bounded + * entry a {@code FalcoInstance} leaves per position, which is the one this repository is responsible + * for. + *

+ *

+ * A second live chunk at the same position — a copy, for instance — holds its own reference to the + * view and keeps working after the entry is gone; the next chunk constructed there simply receives a + * new one. The view is derived from the tracker on every read, so two of them for one position are + * two caches of the same answer and never two different answers. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ApiStatus.Internal +public final class ChunkViewerCache { + + /** + * Blocks the creation of an instance because this class only reaches into a foreign map. + */ + private ChunkViewerCache() { + } + + /** + * Removes the cached view of a chunk position. + * + * @param instance the instance the chunk belonged to + * @param chunkX the chunk X + * @param chunkZ the chunk Z + * @return true if an entry was removed, false if there was none or the tracker is a foreign + * implementation + */ + public static boolean release(Instance instance, int chunkX, int chunkZ) { + if (!(instance.getEntityTracker() instanceof EntityTrackerImpl tracker)) return false; + final EntityTrackerImpl.TargetEntry entry = + tracker.targetEntries[EntityTracker.Target.PLAYERS.ordinal()]; + + // keySet().remove(...) rather than remove(...), because the value type of that map is a + // private nested class and naming what remove would return is not allowed here. + return entry.viewers.keySet().remove(new EntityTrackerImpl.ChunkViewKey(List.of(), chunkX, chunkZ)); + } + + /** + * Reports how many views the tracker of an instance currently caches. + * + * @param instance the instance to read + * @return the amount of cached views, or {@code -1} if the tracker is a foreign implementation + */ + public static int size(Instance instance) { + if (!(instance.getEntityTracker() instanceof EntityTrackerImpl tracker)) return -1; + return tracker.targetEntries[EntityTracker.Target.PLAYERS.ordinal()].viewers.size(); + } +} +``` + +Only the `PLAYERS` entry is touched, because `EntityTrackerImpl#viewable:208` only ever writes into that one. + +- [ ] **Step 4: Call it from the unload** + +In `ChunkLifecycle#unload`, after the loader was told: + +```java + this.persistence.unloaded(falcoChunk); + // Last, because everything above may still want to reach the viewers of this chunk. The view + // object stays alive in the chunk itself; what goes is the entry that kept it findable, which + // is what nothing in Minestom ever removes. + ChunkViewerCache.release(this.owner, chunkX, chunkZ); +``` + +- [ ] **Step 5: Run it, then the module** + +```bash +./gradlew :falco-instance:test --tests "*ChunkViewerCacheTest*" +./gradlew :falco-instance:test +``` + +Expected: PASS, three and then 185. `FalcoInstanceTest#testAPlayerBecomesAViewerOfTheChunksAroundIt` is the net here: it is the only case that reads the viewers of a chunk, and a release that removed the wrong entry would take its viewers with it. + +- [ ] **Step 6: Extend the leak test in `falco-benchmarks`** + +Add a third nested class to `ChunkViewerCacheLeakTest`: + +```java + /** + * The test that shows the leak being cleaned up rather than merely being smaller. + */ + @Nested + @DisplayName("for a FalcoInstance across a load and unload cycle") + class ForAFalcoInstanceThatUnloads { + + /** + * How many load and unload cycles the cache is measured across. + */ + private static final int CYCLES = 64; + + /** + * Establishes that a cycle leaves the cache exactly as it found it. + */ + @Test + @DisplayName("gives the entry back when the chunk goes") + void testTheCacheReturnsToItsSize() { + final FalcoInstance falco = MinestomChunks.newFalcoInstance(); + + try { + final int before = viewerCacheSize(falco); + + for (int cycle = 0; cycle < CYCLES; cycle++) { + falco.unloadChunk(falco.loadChunk(cycle, cycle).join()); + } + final int after = viewerCacheSize(falco); + + System.out.printf("viewer cache of a FalcoInstance: %d cycles, %d -> %d entries%n", + CYCLES, before, after); + assertEquals(before, after, "a load and unload cycle has to be neutral, but the cache grew by " + + (after - before) + " entries over " + CYCLES + " cycles"); + } finally { + MinestomChunks.release(falco); + } + } + } +``` + +The existing `ForAContainer` case stays exactly as it is: it measures Minestom's behaviour, not Falco's, and that behaviour is unchanged. The class javadoc's sentence *"its own unload path does not clear the entry either"* is now false and has to be rewritten to say what happens instead, with a pointer to `ChunkViewerCache`. Raise its `@version` to `1.1.0`. + +- [ ] **Step 7: Run the benchmark module tests** + +```bash +./gradlew :falco-benchmarks:test --tests "*ChunkViewerCacheLeakTest*" -i +``` + +Expected: PASS, three. + +- [ ] **Step 8: Prove it bites** + +Comment out the `ChunkViewerCache.release` call in `ChunkLifecycle#unload` and watch both new cases fail with a growth of 32 and 64 entries. Restore it. + +- [ ] **Step 9: Commit** + +```bash +git add falco-instance/src/main/java/net/minestom/server/instance/ChunkViewerCache.java \ + falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkLifecycle.java \ + falco-instance/src/test/java/net/minestom/server/instance/ChunkViewerCacheTest.java \ + falco-benchmarks/src/test/java/net/minestom/server/instance/ChunkViewerCacheLeakTest.java +git commit -m "fix(instance): give the viewer cache entry back when a chunk unloads" +``` + +--- + +### Task 10: One chunk, both extensions — US-3.06 + +**Files:** +- Create: `falco-light/src/main/java/net/onelitefeather/falco/light/ChunkLightListener.java` +- Rewrite: `falco-light/src/main/java/net/onelitefeather/falco/light/FalcoLightingChunk.java` +- Modify: `falco-light/build.gradle.kts` +- Modify: `falco-light/src/main/java/net/onelitefeather/falco/light/ChunkLightScheduler.java` (javadoc of `supplier()`) +- Modify: `falco-demo/src/main/java/net/onelitefeather/falco/demo/ServerStack.java` +- Test: `falco-light/src/test/java/net/onelitefeather/falco/light/FalcoLightingChunkTest.java` +- Test: `falco-demo/src/test/java/net/onelitefeather/falco/demo/ServerStackTest.java` + +**Interfaces:** +- Consumes: `ChunkLifecycleListener`, `ChunkLifecycleEvent`, `FalcoChunk` from Task 8. +- Produces: `ChunkLightListener(ChunkLightScheduler scheduler)` implementing `ChunkLifecycleListener`, and `FalcoLightingChunk extends FalcoChunk implements LightUpdateAware`. + +**What was actually still missing, read out of the code rather than out of the design.** Stage 1 already removed the structural half of the problem: `FalcoChunk` extends `Chunk`, not `DynamicChunk`, so `FalcoLightingChunk` could extend it the day stage 1 landed. Three things were left. + +1. **The four hooks were occupied by inheritance.** `FalcoLightingChunk` overrode `setBlock`, `onLoad`, `tick` and `invalidate`, so a second extension had nowhere to go. Task 8 fixed that. +2. **The block position had no route that was not an override.** `FalcoLightingChunk:128` hands `markChanged` the exact coordinates, which is what lets the engine replay one position instead of searching nine chunks; a listener with only load, publish, tick and unload would have thrown that away and made every write a full chunk search. `onBlockChange` is that route. +3. **The module edge.** `falco-light` does not depend on `falco-instance`, on purpose — `FalcoLightingChunk`'s own comment argues that a lighting chunk needs the light engine and nothing else. That argument stops holding here: a chunk cannot be a `FalcoChunk` without `falco-instance` on the compile path, and `ChunkLightScheduler#deliver:452` reaches its result through `chunk instanceof LightUpdateAware`, a type of `falco-light` that the chunk has to implement. One of the two modules has to see the other. + +**The decision, with the alternatives that were rejected.** `falco-light` gains `compileOnly(project(":falco-instance"))`. Everything the light engine itself does — `ChunkLightService`, `ChunkLightPropagator`, the scheduler, the nibble handling — keeps working with `falco-instance` absent; only `FalcoLightingChunk` and `ChunkLightListener` need it, and a consumer who uses the supplier adds the second module, which `falco-bom` already publishes next to the first. + +- An `api` dependency was rejected: it would put `falco-instance` on the classpath of every consumer of the light engine, including the ones running a plain `InstanceContainer`. +- Moving the combination into `falco-instance` was rejected: the edge would only point the other way, and `falco-instance` would then depend on `falco-light` for `LightUpdateAware`. +- A `Consumer` sink on the scheduler, so that neither module needs the other, was rejected because it moves the shipped integration into applications: every consumer would have to write the wiring, and the demo would remain the only place where the two are combined. + +- [ ] **Step 1: Write the failing test** + +Append to `FalcoLightingChunkTest.java`: + +```java + @Test + @DisplayName("is a Falco chunk, so a Falco instance can hold it") + void testTheLightingChunkIsAFalcoChunk(Env env) { + final ChunkLightScheduler scheduler = new ChunkLightScheduler(new ChunkLightService()); + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + instance.setChunkSupplier(scheduler.supplier()); + + final Chunk chunk = instance.loadChunk(0, 0).join(); + + assertInstanceOf(FalcoLightingChunk.class, chunk); + assertInstanceOf(FalcoChunk.class, chunk, + "the whole point of US-3.06: one chunk instance serves the lifecycle and the light"); + assertTrue(chunk.isLoaded()); + instance.unloadChunk(chunk); + assertFalse(chunk.isLoaded(), "a Falco instance can reach the unload hook of this chunk"); + } + + @Test + @DisplayName("keeps its storage lazy, so it costs what stage 2 measured") + void testTheLightingChunkHoldsNoSections(Env env) { + final ChunkLightScheduler scheduler = new ChunkLightScheduler(new ChunkLightService()); + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + + final FalcoChunk chunk = new FalcoLightingChunk(scheduler, instance, 0, 0); + + assertEquals(0, chunk.storage().materialisedSections(), + "a lighting chunk is a Falco chunk now, so it starts with no section of its own either"); + assertFalse(chunk.hasHeightmaps()); + } + + @Test + @DisplayName("lets a second extension sit beside the light") + void testASecondListenerFitsBesideTheLight(Env env) { + final ChunkLightScheduler scheduler = new ChunkLightScheduler(new ChunkLightService()); + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + final AtomicInteger ticks = new AtomicInteger(); + final FalcoChunk chunk = new FalcoLightingChunk(scheduler, instance, 0, 0); + + chunk.addLifecycleListener(new ChunkLifecycleListener() { + + @Override + public void onTick(ChunkLifecycleEvent event) { + ticks.incrementAndGet(); + } + }); + chunk.tick(1L); + + assertEquals(1, ticks.get(), + "before this stage the light occupied the only extension point a chunk had"); + } +``` + +Add the imports for `FalcoChunk`, `FalcoInstance`, `ChunkLifecycleListener`, `ChunkLifecycleEvent` and `AtomicInteger`. + +- [ ] **Step 2: Run it and watch it fail** + +```bash +./gradlew :falco-light:test --tests "*FalcoLightingChunkTest*" +``` + +Expected: compilation failure — `falco-instance` is not on the test compile path of `falco-light`. + +- [ ] **Step 3: Add the module edge** + +`falco-light/build.gradle.kts`, comment-free: + +```kotlin + compileOnly(project(":falco-instance")) + testImplementation(project(":falco-instance")) +``` + +- [ ] **Step 4: Write the listener** + +```java +package net.onelitefeather.falco.light; + +import net.minestom.server.instance.block.Block; +import net.onelitefeather.falco.instance.ChunkLifecycleEvent; +import net.onelitefeather.falco.instance.ChunkLifecycleListener; +import net.onelitefeather.falco.instance.FalcoChunk; +import org.jetbrains.annotations.ApiStatus; + +/** + * The {@link ChunkLightListener} class reports the changes of a chunk to a + * {@link ChunkLightScheduler}, without being that chunk. + *

+ * These three reports used to be three overrides of {@code FalcoLightingChunk}, which meant that + * light occupied the only extension point a chunk had: a class has one superclass, so a server which + * wanted Falco's light and anything else on the same chunk had to pick one. As a listener they + * compose, and the chunk keeps only what genuinely needs to live on it — the cached light packet, + * which is per chunk and cannot be held by a listener registered once for a whole instance. + *

+ *

+ * What is reported is a position and not merely a chunk. {@link #onBlockChange} knows exactly which + * block moved, and handing that on is what lets the engine replay one position instead of searching + * nine chunks; a chunk which arrives from a generator or a loader has no such position to offer, so + * {@link #onLoad} reports a change of unknown extent and pays for one search. + *

+ *

+ * This type is experimental. The light engine is new and its API may still change. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ApiStatus.Experimental +public final class ChunkLightListener implements ChunkLifecycleListener { + + /** + * The scheduler which decides when the light of a chunk is computed. + */ + private final ChunkLightScheduler scheduler; + + /** + * Creates a listener reporting to a scheduler. + * + * @param scheduler the scheduler which decides when the light of a chunk is computed + */ + public ChunkLightListener(ChunkLightScheduler scheduler) { + this.scheduler = scheduler; + } + + /** + * Reports the changed position, which is what lets the light be updated rather than searched. + * + * @param chunk the chunk which received the block + * @param x the block X + * @param y the block Y + * @param z the block Z + * @param block the block which was written + */ + @Override + public void onBlockChange(FalcoChunk chunk, int x, int y, int z, Block block) { + this.scheduler.markChanged(chunk.getInstance(), chunk.getChunkX(), chunk.getChunkZ(), x, y, z); + } + + /** + * Reports the chunk dirty as soon as its instance has taken it. + *

+ * Without this a world that is only ever read would stay black: no block ever changes, so nothing + * would ever ask for the light of a chunk that came straight from a loader or a generator. The + * neighbours are reported with it, because a chunk that appears next to an already lit one can + * send light into it that was not there when it was lit. + *

+ * + * @param event the chunk which finished loading + */ + @Override + public void onLoad(ChunkLifecycleEvent event) { + final FalcoChunk chunk = event.chunk(); + this.scheduler.markChanged(chunk.getInstance(), chunk.getChunkX(), chunk.getChunkZ()); + } + + /** + * Drives the scheduler, once per tick of every chunk it is installed on. + * + * @param event the chunk which was ticked, and the tick time + */ + @Override + public void onTick(ChunkLifecycleEvent event) { + this.scheduler.onTick(event.chunk().getInstance(), event.time()); + } +} +``` + +- [ ] **Step 5: Rewrite the chunk** + +```java +public class FalcoLightingChunk extends FalcoChunk implements LightUpdateAware { + + /** + * The light packet of this chunk, rebuilt only when somebody asks for it after an invalidation. + */ + private final CachedPacket lightCache = new CachedPacket( + () -> new UpdateLightPacket(getChunkX(), getChunkZ(), createLightData(false)) + ); + + /** + * Creates a chunk which reports its changes to the given scheduler. + * + * @param scheduler the scheduler which decides when the light of this chunk is computed + * @param instance the instance this chunk belongs to + * @param chunkX the chunk x coordinate + * @param chunkZ the chunk z coordinate + */ + public FalcoLightingChunk(ChunkLightScheduler scheduler, Instance instance, int chunkX, int chunkZ) { + super(instance, chunkX, chunkZ); + addLifecycleListener(new ChunkLightListener(scheduler)); + } + + @Override + public void invalidate() { + super.invalidate(); + this.lightCache.invalidate(); + } + + @Override + public void onLightUpdated() { + if (!isLoaded()) { + return; + } + this.lightCache.invalidate(); + sendPacketToViewers(this.lightCache); + } +} +``` + +Three overrides are gone — `setBlock`, `onLoad` and `tick` — and their javadoc moves to `ChunkLightListener`. The class comment needs four changes and one deletion: + +- the paragraph *"Why this lives in falco-light and not in falco-instance"* is now wrong in its premise and has to say what actually happened: the class needs `falco-instance` at compile time, gets it as a `compileOnly` dependency, and a consumer who uses `ChunkLightScheduler#supplier()` needs both modules on the classpath while a consumer of the bare light engine needs neither; +- the paragraph *"This class holds no computation logic on purpose"* stays and gets sharper: two overrides now, both about a packet; +- the paragraph about `isLoaded` not being overridden stays and its reference to `DynamicChunk` becomes `FalcoChunk`, which has the same property — a freshly constructed chunk reports itself loaded, so a batch against it is not silently skipped; +- a new paragraph states what the chunk gained by changing superclass: the lazy sections, the on-demand heightmaps and the single block index map of stage 2, which is 25 objects and 840 bytes against 192 and 6 848 for the `DynamicChunk` it used to extend; +- `@version` to `2.0.0`, and the `supplier()` javadoc of `ChunkLightScheduler` gains one line saying the chunks it produces are `FalcoChunk`s and work in a `FalcoInstance` as well as in an `InstanceContainer`. Raise its `@version`. + +- [ ] **Step 6: Run the light module** + +```bash +./gradlew :falco-light:test +``` + +Expected: PASS, 192 (189 from stage 2 plus the three new cases). The whole existing light suite is the net here: `ChunkBorderLightTest`, `SkyLightUpdateTest`, `IncrementalLightUpdateTest` and `LightEngineEquivalenceTest` all drive the chunk and would notice a report that no longer arrives. + +- [ ] **Step 7: Fix the demo, which documented the impossibility** + +`ServerStack:29-39` explains at length that both stacks run on an `InstanceContainer` because `FalcoInstance` cannot hold a `FalcoLightingChunk`, and `ServerStack#note:203` prints that to the log. Both stop being true. Change the Falco stack to build a `FalcoInstance` with the light supplier, make `note()` say what the stack now consists of, and update `ServerStackTest#testTheFalcoStackExplainsWhyTheFalcoInstanceIsMissing` — which asserts that the note mentions `FalcoInstance` — into a case that asserts the stack uses one. Raise `ServerStack`'s `@version` to `2.0.0`. + +**Keep the comparison honest while doing it.** The two stacks exist to differ in one variable at a time, and the vanilla stack stays on an `InstanceContainer`. Changing the Falco side to a `FalcoInstance` adds a second variable to the comparison, and that has to be written into the class comment rather than glossed over: from this stage on the two stacks differ in the loader, in the chunk type **and** in the instance, and a figure taken from the demo can no longer be attributed to any one of them. + +- [ ] **Step 8: Run the demo module** + +```bash +./gradlew :falco-demo:test +``` + +Expected: PASS, 139. + +- [ ] **Step 9: Prove the combination is real** + +Delete `addLifecycleListener(new ChunkLightListener(scheduler));` from the constructor and watch `SkyLightUpdateTest` and `IncrementalLightUpdateTest` go dark — a world which never reports a change is never lit. Restore it. Then make `FalcoLightingChunk` extend `DynamicChunk` again and watch `testTheLightingChunkIsAFalcoChunk` fail with the `FalcoInstanceException` that names the wrong supplier, which is precisely the message the demo used to have to work around. + +- [ ] **Step 10: Commit** + +```bash +git add falco-light/build.gradle.kts \ + falco-light/src/main/java/net/onelitefeather/falco/light/ChunkLightListener.java \ + falco-light/src/main/java/net/onelitefeather/falco/light/FalcoLightingChunk.java \ + falco-light/src/main/java/net/onelitefeather/falco/light/ChunkLightScheduler.java \ + falco-light/src/test/java/net/onelitefeather/falco/light/FalcoLightingChunkTest.java \ + falco-demo/src/main/java/net/onelitefeather/falco/demo/ServerStack.java \ + falco-demo/src/test/java/net/onelitefeather/falco/demo/ServerStackTest.java +git commit -m "feat(light)!: put the lifecycle and the light on one chunk instance" +``` + +--- + +### Task 11: The chunk index without a box — US-3.05 + +**Files:** +- Modify: `settings.gradle.kts` +- Modify: `falco-instance/build.gradle.kts` +- Modify: `falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkRegistry.java` +- Test: `falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkLookupAllocationTest.java` +- Create: `falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/ChunkLookupBenchmark.java` + +**Interfaces:** +- Consumes: `ChunkRegistry` from Task 2. +- Produces: no API change. `chunk(long)`, `chunk(int,int)`, `chunks()`, `snapshot()`, `size()` keep their signatures; only what is behind them changes. + +**What this is and is not.** §4.3 of the spec is explicit: this is **not** sold as a performance change. `ConcurrentHashMap#get` boxes its key, and that allocation is real and can be counted. What it costs is not established, because `getChunk` is reached on a chunk change rather than per block — `ChunkCache` memoises in between. The deliverable of this task is therefore the counted allocation and a benchmark that prices the two maps against each other, not a claim. + +**The dependency this needs, checked before it was written down.** + +```bash +./gradlew :falco-instance:dependencies --configuration compileClasspath | grep flare +./gradlew :falco-instance:dependencies --configuration testRuntimeClasspath | grep flare +``` + +The first prints nothing and the second prints `space.vectrix.flare:flare:2.0.1` and `space.vectrix.flare:flare-fastutil:2.0.1`. Minestom depends on flare and hides it from its compile classpath, so `Long2ObjectSyncMap` is present at runtime for every Minestom server that exists and absent at compile time here. `compileOnly` is exactly the right shape: no consumer gains a dependency it did not already have through Minestom. + +`Long2ObjectSyncMap` is not the copy-on-write map the javadoc of `FalcoInstance` used to warn about. It is a Go-style `sync.Map`: a read map that satisfies lookups without a lock and a dirty map that takes the writes, promoted when the misses add up. Reads take no lock and box nothing; a write after many misses rebuilds the dirty map, which is O(n) and lands on the load and unload path, where a tick partition is created and an event is dispatched anyway. That trade is stated here and priced by the benchmark below, not asserted. + +**Only the published chunks change.** `loadingChunks` stays a `ConcurrentHashMap>`, because its `compute` is the lock of a position and the exact atomicity of that method is what `FalcoInstanceLoadRaceTest` protects. Swapping it for a map whose atomicity guarantees have to be re-read from a third-party source is not a boxing question and does not belong in a story marked *Could*. + +- [ ] **Step 1: Write the failing test** + +```java +package net.onelitefeather.falco.instance; + +import com.sun.management.ThreadMXBean; +import net.minestom.server.world.DimensionType; +import net.minestom.testing.Env; +import net.minestom.testing.extension.MicrotusExtension; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; + +import java.lang.management.ManagementFactory; +import java.util.UUID; + +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.junit.jupiter.api.Assumptions.assumeTrue; + +/** + * Counts what looking a chunk up allocates, which is US-3.05. + *

+ * A {@code ConcurrentHashMap} boxes its key on every call, and the chunk index of a + * position is far outside the range {@code Long#valueOf} caches, so every lookup is a sixteen byte + * object that lives until the next young collection. This counts them. It says nothing about time, + * on purpose: the design refuses to sell the change as a speed gain, because {@code getChunk} is + * reached on a chunk change rather than per block and {@code ChunkCache} memoises in between. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ExtendWith(MicrotusExtension.class) +@DisplayName("What a chunk lookup allocates") +class ChunkLookupAllocationTest { + + /** + * How many lookups the measurement performs. + */ + private static final int LOOKUPS = 500_000; + + /** + * How many lookups run before the measurement, so the loop is compiled. + */ + private static final int WARMUP = 100_000; + + /** + * Where the looked up chunk is published, so no compiler may drop the lookup. + */ + private static volatile Object sink; + + /** + * Performs the given number of lookups and reports what the calling thread allocated. + * + * @param registry the registry to look up in + * @param times how many lookups to perform + * @return the bytes the calling thread allocated during the loop + */ + private static long allocatedWhileLookingUp(ChunkRegistry registry, int times) { + final ThreadMXBean threads = (ThreadMXBean) ManagementFactory.getThreadMXBean(); + final long before = threads.getCurrentThreadAllocatedBytes(); + + for (int index = 0; index < times; index++) { + sink = registry.chunk(0, 0); + } + return threads.getCurrentThreadAllocatedBytes() - before; + } + + @Test + @DisplayName("allocates nothing at all") + void testALookupIsAllocationFree(Env env) { + final ThreadMXBean threads = (ThreadMXBean) ManagementFactory.getThreadMXBean(); + assumeTrue(threads.isThreadAllocatedMemorySupported(), + "this JVM cannot report per thread allocation, so the question cannot be answered here"); + threads.setThreadAllocatedMemoryEnabled(true); + + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + instance.loadChunk(0, 0).join(); + final ChunkRegistry registry = instance.registry(); + assertNotNull(registry.chunk(0, 0), "the position has to carry a chunk, or this loop measures a miss"); + + allocatedWhileLookingUp(registry, WARMUP); + final long allocated = allocatedWhileLookingUp(registry, LOOKUPS); + + System.out.printf("chunk lookups: %,d -> %,d B (%.3f B each)%n", + LOOKUPS, allocated, (double) allocated / LOOKUPS); + assertTrue(allocated < LOOKUPS, "a chunk lookup allocated " + allocated + " B over " + LOOKUPS + + " lookups, which is more than a byte each: the index is still being boxed"); + } +} +``` + +- [ ] **Step 2: Run it and watch it fail** + +```bash +./gradlew :falco-instance:test --tests "*ChunkLookupAllocationTest*" +``` + +Expected: **failure**, at roughly 16 B per lookup. Print the number: it is the before-figure of this task and belongs in the stage result. + +- [ ] **Step 3: Add the dependency** + +`settings.gradle.kts`, in the version catalog: + +```kotlin + version("flare", "2.0.1") + library("flare.fastutil", "space.vectrix.flare", "flare-fastutil").versionRef("flare") +``` + +`falco-instance/build.gradle.kts`: + +```kotlin + compileOnly(libs.flare.fastutil) + testImplementation(libs.flare.fastutil) +``` + +Then check that the pinned version is the one Minestom brings at runtime, so that compiling against one and running against another cannot happen: + +```bash +./gradlew :falco-instance:dependencies --configuration testRuntimeClasspath | grep flare +``` + +Both lines have to say `2.0.1`. If Minestom is bumped later and brings a different one, this is the line that has to move with it. + +- [ ] **Step 4: Change the map** + +In `ChunkRegistry`: + +```java + /** + * The loaded chunks, keyed by the chunk index of their position. + *

+ * A primitive keyed map rather than a {@code ConcurrentHashMap}, which boxed its key + * on every lookup — sixteen bytes per call, counted by {@code ChunkLookupAllocationTest}. This is + * not offered as a speed change and no figure of this repository claims one: {@code getChunk} is + * reached on a chunk change rather than per block, because {@code ChunkCache} memoises in between, + * so the allocation is established and its cost is not. + *

+ *

+ * {@code Long2ObjectSyncMap} is a read map plus a dirty map in the shape of Go's {@code sync.Map}, + * not the copy-on-write map underneath {@code InstanceContainer}. Lookups take no lock; a write + * after a run of misses rebuilds the dirty map, which is linear and lands on the load and unload + * path, where a tick partition is created and an event is dispatched anyway. + * {@code ChunkLookupBenchmark} prices both sides. + *

+ */ + private final Long2ObjectSyncMap chunks = Long2ObjectSyncMap.hashmap(); +``` + +`chunk(long)` becomes `this.chunks.get(index)` on the primitive overload, `remove` inside `ChunkRegistry#remove` becomes `this.chunks.remove(index, chunk)` on the primitive overload, `put` becomes `this.chunks.put(index, chunk)`. `chunks()`, `snapshot()`, `size()` and `idle()` are unchanged in body — `Long2ObjectSyncMap` implements `Long2ObjectMap`, so `values()` and `isEmpty()` are there. + +- [ ] **Step 5: Run the test, then the module** + +```bash +./gradlew :falco-instance:test --tests "*ChunkLookupAllocationTest*" +./gradlew :falco-instance:test +``` + +Expected: PASS at `0.000 B each`, and 186 for the module. + +- [ ] **Step 6: Write the benchmark that prices the trade** + +```java +package net.onelitefeather.falco.benchmark.instance; + +import net.minestom.server.coordinate.CoordConversion; +import net.minestom.server.instance.Chunk; +import org.openjdk.jmh.annotations.Benchmark; +import org.openjdk.jmh.annotations.BenchmarkMode; +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.infra.Blackhole; +import space.vectrix.flare.fastutil.Long2ObjectSyncMap; + +import java.util.Map; +import java.util.concurrent.ConcurrentHashMap; +import java.util.concurrent.TimeUnit; + +/** + * Prices the boxed chunk index against the unboxed one, on the lookup and on the write. + *

+ * US-3.05 asks for the boxing to go and the design refuses to sell that as a speed change, because + * the cost of the boxing is not established. This benchmark is what would establish it, and it + * measures both directions on purpose: the lookup, which is what the change is for, and the write, + * which is where the map that removes the boxing is more expensive. A change that reports only the + * side it improves is not a measurement. + *

+ *

+ * Both maps are driven with the same key sequence and the same content. Neither arm touches a real + * chunk — the value is a plain {@code Object} standing in for one — because the question is about the + * map and a chunk would put a two hundred kilobyte object into a cache line argument. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@State(Scope.Benchmark) +@BenchmarkMode(Mode.AverageTime) +@OutputTimeUnit(TimeUnit.NANOSECONDS) +public class ChunkLookupBenchmark { + + /** + * How many chunk positions the maps hold, which is roughly a view distance of eight, sixteen and + * a streaming world. + */ + @Param({"289", "1089", "4096"}) + public int positions; + + /** + * The boxed map, the shape this stage replaced. + */ + private Map boxed; + + /** + * The primitive map, the shape this stage installed. + */ + private Long2ObjectSyncMap primitive; + + /** + * The keys, in the order the benchmark walks them. + */ + private long[] keys; + + /** + * The value every key maps to. + */ + private final Object value = new Object(); + + /** + * Fills both maps with the same content. + */ + @Setup + public void setUp() { + this.boxed = new ConcurrentHashMap<>(); + this.primitive = Long2ObjectSyncMap.hashmap(); + this.keys = new long[this.positions]; + + final int side = (int) Math.ceil(Math.sqrt(this.positions)); + for (int index = 0; index < this.positions; index++) { + final long key = CoordConversion.chunkIndex(index % side, index / side); + this.keys[index] = key; + this.boxed.put(key, this.value); + this.primitive.put(key, this.value); + } + } + + /** + * Walks every position through the boxed map. + * + * @param blackhole where the results go + */ + @Benchmark + public void boxedLookup(Blackhole blackhole) { + for (long key : this.keys) blackhole.consume(this.boxed.get(key)); + } + + /** + * Walks every position through the primitive map. + * + * @param blackhole where the results go + */ + @Benchmark + public void primitiveLookup(Blackhole blackhole) { + for (long key : this.keys) blackhole.consume(this.primitive.get(key)); + } + + /** + * Puts and removes one position in the boxed map, which is what a load and an unload do. + * + * @param blackhole where the results go + */ + @Benchmark + public void boxedLoadAndUnload(Blackhole blackhole) { + final long key = CoordConversion.chunkIndex(9999, 9999); + blackhole.consume(this.boxed.put(key, this.value)); + blackhole.consume(this.boxed.remove(key)); + } + + /** + * Puts and removes one position in the primitive map. + * + * @param blackhole where the results go + */ + @Benchmark + public void primitiveLoadAndUnload(Blackhole blackhole) { + final long key = CoordConversion.chunkIndex(9999, 9999); + blackhole.consume(this.primitive.put(key, this.value)); + blackhole.consume(this.primitive.remove(key)); + } +} +``` + +`falco-benchmarks/build.gradle.kts` needs `jmhImplementation(libs.flare.fastutil)` — comment-free, one line. + +- [ ] **Step 7: Run it in the scouting configuration and write the numbers down** + +```bash +./gradlew :falco-benchmarks:jmh -Pjmh.quick -Pjmh.include="ChunkLookupBenchmark" +``` + +Record the four arms and their `gc.alloc.rate.norm` in the stage result, **with the sentence that the configuration disqualifies the timings from being quoted** — one fork, three iterations, on a machine that is not idle. What is citable from this run is the allocation column, which is deterministic: the boxed lookup arm allocates sixteen bytes per position and the primitive one zero. + +- [ ] **Step 8: Prove the allocation test bites** + +Change `ChunkRegistry#chunk(int,int)` back to a `ConcurrentHashMap` lookup and watch `ChunkLookupAllocationTest` fail with roughly 16 B per lookup. Restore it. + +- [ ] **Step 9: Commit** + +```bash +git add settings.gradle.kts falco-instance/build.gradle.kts falco-benchmarks/build.gradle.kts \ + falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkRegistry.java \ + falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkLookupAllocationTest.java \ + falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/ChunkLookupBenchmark.java +git commit -m "perf(instance): look a chunk up without boxing its index" +``` + +--- + +### Task 12: Re-run everything and record what the stage cost + +**Files:** +- Modify: `docs/superpowers/plans/2026-08-02-falco-instance-facade.md` (this file) + +**Interfaces:** +- Consumes: everything above. +- Produces: a `## Stage 3 result` section. + +**This is the acceptance gate of the stage.** Nothing here is new code; everything here is a number that has to exist before the stage may be called done. + +- [ ] **Step 1: The whole suite** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +./gradlew :falco-instance:test :falco-anvil:test :falco-light:test :falco-demo:test :falco-benchmarks:test --rerun-tasks +``` + +Expected: all green. Record the five counts against T4 of the starting point: 143 / 193 / 189 / 139 / 38 became something larger in three of them and has to be unchanged in `falco-anvil`. A count that fell anywhere is a test that was deleted, and deleting a test during a refactoring is the one thing this plan must not have done. + +- [ ] **Step 2: The footprint** + +```bash +./gradlew :falco-benchmarks:test --tests "*ChunkFootprintTest*" -i +./gradlew :falco-benchmarks:test --tests "*ChunkFootprintTest*" -Pfalco.compactHeaders -i +``` + +Record the fresh chunk against T1 (25 objects, 840 B) and the per-chunk instance cost against T3 (161 B). The first has one reference field more than it did — Task 8 — and the second is unchanged by this stage, because it measures construction and the entry that goes now goes on unload. + +- [ ] **Step 3: The equivalence, which carries US-1.03** + +```bash +./gradlew :falco-benchmarks:test --tests "*FalcoChunkEquivalenceTest*" -i +``` + +Eighteen fixtures, every position and both heightmaps of every column. Nothing in this stage touches block storage, and that is exactly why this has to be run: a stage that only moved code around has no excuse for a difference here. + +- [ ] **Step 4: The javadoc** + +```bash +./gradlew :falco-instance:javadoc :falco-light:javadoc +``` + +`-Werror` is on. Seven new public types shipped in this stage and every public member of them needs a complete comment. + +- [ ] **Step 5: Write the result section** + +Append `## Stage 3 result` to this file with, at minimum: + +- the five test counts, before and after; +- the fresh chunk footprint, before and after, with the object header mode and the JOL mode; +- the two numbers of `ChunkLifecycleAllocationTest`, both arms, with the machine; +- the before and after of `ChunkLookupAllocationTest`; +- the four arms of `ChunkLookupBenchmark` with the sentence that disqualifies their timings; +- the viewer cache figures, before and after, over 64 cycles; +- the line counts of every file in `falco-instance/src/main/java/net/onelitefeather/falco/instance/`; +- **what this stage did not achieve**, in its own paragraph. At the time of writing the plan the honest candidates are: the container's unbounded viewer cache growth, which cannot be reached from outside Minestom; the module edge from `falco-light` to `falco-instance`, which reverses an argument the old `FalcoLightingChunk` javadoc made and is a cost rather than a win; the split package of `ChunkViewerCache`, which closes the module path; and the second variable the demo comparison gained in Task 10. + +- [ ] **Step 6: Commit** + +```bash +git add docs/superpowers/plans/2026-08-02-falco-instance-facade.md +git commit -m "docs(plan): record what stage 3 measured" +``` + +--- + +## Definition of done + +- [ ] `placeBlock`, `breakBlock`, the neighbour updates, the recursion guard and all four save paths have tests, and those tests were written before the code moved +- [ ] `FalcoInstance` declares exactly four fields, every one of them final and one of the four parts, and `InstanceFacadeTest` fails when a fifth appears — proven by adding one +- [ ] `publish` and `completeLoad` are reachable in a test without driving a full load, and the refused-publish case is deterministic in a single thread +- [ ] `ChunkLifecycleListener` exists, two listeners on one chunk are both notified on all five reports, and a single listener is stored without being wrapped +- [ ] A lifecycle transition on a chunk with no listener allocates nothing, **counted**, with a positive control that proves the counter can see allocations at all +- [ ] `FalcoLightingChunk` is a `FalcoChunk`, a `FalcoInstance` loads and unloads one, and a second listener fits beside the light +- [ ] The demo runs its Falco stack on a `FalcoInstance`, and the note that said it could not is gone +- [ ] A load and unload cycle leaves the viewer cache exactly where it found it, over 64 cycles, proven by removing the release and watching it grow +- [ ] A chunk lookup allocates nothing, counted before and after, with the benchmark that prices the write side of the trade +- [ ] `ChunkFootprintTest` still asserts a declared per-class table with no tolerance anywhere in it, re-declared for the one field `FalcoChunk` gained +- [ ] All five module suites pass, with counts recorded against the stage 2 result, and no count fell +- [ ] `:falco-instance:javadoc` and `:falco-light:javadoc` pass with `-Werror` +- [ ] Every new public type carries `@ApiStatus.Experimental`, `@author`, `@version` and `@since 0.4.0`; every modified type has its `@version` raised + +## What stage 3 deliberately does not do + +Named here so that a reviewer does not read them as omissions. + +**It does not build a shared instance (US-4.01 to US-4.04).** That is stage 4 and it rests on US-1.05, which stage 1 delivered. Nothing here is a step towards it and nothing here blocks it. + +**It does not fix the viewer cache leak of `InstanceContainer` (M14).** The container hands its tracker a fresh `unmodifiableList` on every chunk construction and `ChunkViewKey#equals` compares that list by identity, so no key built from outside can ever match one of its entries. `ChunkViewerCacheLeakTest` keeps measuring it because it is the reason the Falco side is worth cleaning up, not because Falco fixed it. + +**It does not remove the `instanceof InstanceContainer` branches of Minestom.** Four places in the server take a different path for anything that is not a container, and three of them are harmless here. The fourth — `InstanceManager#unregisterInstance` not unloading chunks — is still answered by `FalcoInstance#unregister`, which is still the reason the class exists. + +**It does not make `FalcoInstance` faster.** Not one line of this stage was written for throughput. The lock granularity is unchanged, the write path does the same work in the same order, and the primitive chunk index is delivered with a counted allocation and an explicit refusal to claim a speed gain. If a benchmark of this stage shows a difference, it is a regression to investigate, not a result to quote. + +**It does not touch block storage.** No change to `BlockStorage`, `LazySectionBlockStorage`, `SectionBlockStorage`, the flyweight, the heightmaps or the palettes. `FalcoChunk` gains one field and five notification points and nothing else, and `FalcoChunkEquivalenceTest` is what says so. + +**It does not remove the last `AtomicBoolean` or the chunk `UUID`.** Both are stage 2 non-goals for reasons that have not changed: `LightCompute#compute` is package-private, and `Chunk.java:48` declares a field a subclass cannot delete. + +**It does not turn `falco-light` into a module that needs `falco-instance` at runtime for everything.** The dependency is `compileOnly` and only two classes of the module use it. A consumer of the bare light engine on a plain `InstanceContainer` adds nothing; a consumer of `ChunkLightScheduler#supplier()` adds `falco-instance`, which `falco-bom` already publishes beside it. That is a real cost and it is booked here rather than hidden. + +**It does not make Falco a named module.** `ChunkViewerCache` puts a class into `net.minestom.server.instance`, which is a split package with Minestom's own module. On the classpath, where every consumer runs today, this is invisible. On the module path it is fatal, and it will stay fatal until either Minestom exposes a way to release a viewer cache entry or that class moves somewhere it cannot reach the map at all. + +## Stage 3 result + +Measured 2026-08-03 on branch `feat/block-storage` at `bf4b4e29`, against Minestom +`2026.06.20-26.1.2` as pinned by the build and JDK 25.0.3 (Temurin), on an AMD Ryzen 7 5800X with +sixteen hardware threads. + +**The machine was not idle at any point of this stage.** Load average moved between 4.2 and 7.2 +across every run recorded below. That decides what may be quoted and what may not, and the split runs +through the whole section: + +- **Citable.** The JOL footprint, because JOL walks a reachable object graph and counts it. The test + counts. The per-thread allocation counters, which came back byte-identical under `-Xint`, + `-XX:-DoEscapeAnalysis`, `-XX:TieredStopAtLevel=1` and the default JIT. The `gc.alloc.rate.norm` + column of the benchmark, which is the same kind of counting. +- **Not citable.** Every `ns/op` in this section, without exception. They come from + `-Pjmh.quick` — one fork, two warmup and three measurement iterations — on that machine. They + answer "is there a difference large enough to see through the noise" and nothing finer. + +### The tests, which need two baselines rather than one + +| module | T4, stage 2 | after the `main` merge | now | stage 3's share | +| --- | ---: | ---: | ---: | ---: | +| `:falco-instance:` | 143 | 152 | **220** | +68 | +| `:falco-anvil:` | 193 | 217 | **217** | 0 | +| `:falco-light:` | 189 | 205 | **210** | +5 | +| `:falco-demo:` | 139 | 166 | **167** | +1 | +| `:falco-benchmarks:` | 38 | 42 | **42** (1 skipped) | 0 | +| `:falco-archunit:` | — | 42 | **43** | +1 | + +All green, no failure, no error. The one skip is `EmptySectionCensusTest`, which needs a real Anvil +world next to the repository and aborts its assumption when there is none — unchanged since stage 1. + +The middle column exists because **`ea776874` merged `main` into this branch between the plan commit +and the first task of the stage**. T4 is therefore not the number stage 3 started from, and a range +diff against T4 attributes the merge's tests to this stage. The column was taken by checking the +worktree out at `e25802f8` — the last commit before task 1 — and running the six suites there, then +returning to the branch. `:falco-archunit:` did not exist in T4 at all; it arrived with the merge. + +No count fell in either step. That was the one thing the stage was not allowed to do. + +### The footprint, which is citable and which sees less than it appears to + +Legacy object headers of twelve bytes, eight byte alignment, sizes through the JOL instrumentation +agent, `falco.compactHeaders=false`: + +| | objects | bytes | +| --- | ---: | ---: | +| fresh chunk, `DynamicChunk` | 192 | 6 848 | +| fresh chunk, `FalcoChunk` | **25** | **840** | +| difference | −167 | **−6 008** | + +The same measurement under `-XX:+UseCompactObjectHeaders` (`falco.compactHeaders=true`, eight byte +headers): 192 / 6 176 against 25 / 760, a difference of −5 416. The two modes must not be quoted +beside each other. + +The instance-side cost per chunk, which is T3: + +| | legacy headers | compact headers | +| --- | ---: | ---: | +| `InstanceContainer` | 185 B | 161 B | +| `FalcoInstance` | **161 B** | **145 B** | + +**Both tables are unchanged from stage 2, and that is a statement about the instrument, not only +about the stage.** Task 8 gave `FalcoChunk` a listener field. The fresh-chunk figure did not move, +because the field is a reference that is `null` on a fresh chunk — no object — and it fitted into +padding the object already carried, so the shallow size did not move either. This is precisely the +seventh injected defect of the stage 2 result, the one that was *not* caught: a comparison built on +object counts and shallow sizes cannot see a field of this shape. The right reading of "the footprint +is unchanged" is "nothing this instrument can see has changed", and the DoD item that asked for the +table to be *re-declared* for the new field turned out to have nothing to re-declare. + +`ChunkFootprintTest` also prints its own residue, unchanged: proving the two chunks equivalent leaves +the fresh Falco chunk at 36 objects and 2 168 bytes, because the check materialises both heightmaps +and one section. That runs after the measurement and lands outside every table above. + +`FalcoChunkEquivalenceTest` — 18 fixtures, every position and both heightmaps of every column — +green. Nothing in this stage touches block storage, which is exactly why it had to be run. + +### What a lifecycle transition allocates, which is US-3.04 + +`ChunkLifecycleAllocationTest`, 200 000 transitions per arm, per-thread allocation from +`com.sun.management.ThreadMXBean`, on the machine named at the top: + +``` +lifecycle transitions: 200.000 without a listener -> 704 B ( 0,004 B each) +lifecycle transitions: 200.000 with one listener -> 4.800.000 B (24,000 B each) +``` + +The second arm is the positive control and is the reason the first one means anything: it publishes +its event into a `static volatile` field, so no compiler may delete the allocation, and it shows the +counter can see one. A null arm on its own would be green against an implementation that allocates on +every transition and merely lets escape analysis remove it. + +### What a chunk lookup allocates, which is US-3.05 + +`ChunkLookupAllocationTest`, 500 000 lookups: + +| | bytes | per lookup | +| --- | ---: | ---: | +| `ConcurrentHashMap` | 8 327 736 | **16.655 B** | +| `Long2ObjectSyncMap` | 240 | **0.000 B** | + +**The before figure only exists at the right position, and the plan named the wrong one.** The test +as drafted measured chunk 0/0, and `CoordConversion#chunkIndex(0, 0)` is `0L` — the one index in the +whole world that `Long#valueOf` serves out of its cache. Over that position the boxed map reports +`0,000 B` as well, so the test was green against the implementation it was written to condemn. It +measures chunk 4/7 instead, whose index is above 2³², and the class javadoc says why the position may +not be moved back. + +Two mutations, because one was not enough. Boxing the key by hand and going through fastutil's +`get(Object)` default **did not** make it red: that box is unwrapped immediately and escape analysis +deletes it. Putting the field back to a `ConcurrentHashMap` **did**, at 13.512 B per lookup. The test +therefore discriminates between the two map implementations, which is what it claims to do, and not +"some boxing somewhere". + +### `ChunkLookupBenchmark`, and a correction to what it was expected to show + +`-Pjmh.quick -Pjmh.include="ChunkLookupBenchmark"`, average time, one full pass over the key set per +operation on the lookup arms and one put plus one remove on the write arms. + +| arm | positions | ns/op (**not citable**) | `gc.alloc.rate.norm` B/op | +| --- | ---: | ---: | ---: | +| `boxedLookup` | 289 | 7 924.6 ± 468.6 | 20 024.0 | +| `boxedLookup` | 1 089 | 36 487.3 ± 818.3 | 80 952.0 | +| `boxedLookup` | 4 096 | 197 171.8 ± 34 205.6 | 322 560.1 | +| `primitiveLookup` | 289 | 1 430.1 ± 11.7 | **0.001** | +| `primitiveLookup` | 1 089 | 5 087.4 ± 85.6 | **0.004** | +| `primitiveLookup` | 4 096 | 20 678.5 ± 3 654.0 | **0.014** | +| `boxedLoadAndUnload` | 289 / 1 089 / 4 096 | 82.9 / 88.4 / 97.2 | 208.0 each | +| `primitiveLoadAndUnload` | 289 / 1 089 / 4 096 | 61.0 / 43.6 / 36.8 | 37.8 / 38.7 / 40.0 | + +Two things in this table contradict what the task expected, and both are recorded rather than +smoothed over. + +**The write side did not get worse.** The benchmark exists because `Long2ObjectSyncMap` pays for a +dirty-map rebuild on writes after a run of misses, and the task was written to put that cost on the +record. In this configuration the primitive map is the cheaper one on the write arm too, and it +allocates a fifth of what the boxed one does. That is a scouting number on a loaded machine and it is +not evidence that the rebuild is free; it is evidence that this benchmark did not provoke it. + +**The boxed lookup arm does not allocate sixteen bytes per position — it allocates 69 to 79 — and +most of that is not boxing.** Traced outside JMH with the same per-thread counter: + +- a box costs 24 B, and 272 of the 289 keys lie outside the autobox cache: 6 528 B per pass, exactly + what the counter reports for a loop that only boxes; +- the remaining ~46.7 B per lookup appear **with a pre-boxed key as well**, so no autoboxing is + involved in them at all; +- they vanish when the keys are spread by a mixing multiplier (0.00 B), and they appear precisely + when the grid crosses the treeify threshold: side 4, 6 and 8 give 0.00 B, side 17 and 33 give + 46.7 and 51.1 B. + +The cause is that `Long#hashCode` of a chunk index is `chunkX ^ chunkZ`, so a view-distance grid maps +onto a handful of buckets, the bins treeify, and `HashMap`/`ConcurrentHashMap` then call +`comparableClassFor` → `Class#getGenericInterfaces` on every lookup, which allocates reflectively. +Identical under `-Xint`, `-XX:-DoEscapeAnalysis` and C1, so it is not a JIT artefact. The primitive +map escapes both costs, because fastutil mixes the long key itself and never treeifies. + +**None of this makes the change a speed change.** `getChunk` is reached on a chunk change rather than +per block, because `ChunkCache` memoises in between, so the counted allocation is established and its +cost to a running server still is not. + +### The viewer cache, T6 and T7 + +`ChunkViewerCacheLeakTest`, entries added to the tracker's cache: + +| constructions | `InstanceContainer` | `FalcoInstance` | +| ---: | ---: | ---: | +| 16 | 16 | **1** | +| 160 | 160 | **0** | +| 1 600 | 1 600 | **0** | + +T7 said one entry per *position*, never removed. `ChunkViewerCacheTest#testALoadAndUnloadCycleIsNeutral` +now says the entry goes back: the cache ends a run of load-and-unload cycles exactly where it started, +and commenting the `ChunkViewerCache.release(...)` call out of `ChunkLifecycle#unload` makes it fail +with `expected: <0> but was: <32>`. **The definition of done says 64 cycles and the test does 32.** +The 64-cycle variant lived in `falco-benchmarks`, where it destabilised `ChunkFootprintTest` through +JUnit ordering, and task 9 removed it rather than leave a flaky assertion standing. T6 is untouched +and cannot be touched from outside Minestom. + +### What the split cost, in lines + +`falco-instance/src/main/java/net/onelitefeather/falco/instance/` plus the one class that had to live +in a Minestom package: + +| file | lines | +| --- | ---: | +| `FalcoChunk.java` | 1 115 | +| `FalcoInstance.java` | **951** | +| `ChunkLifecycle.java` | 632 | +| `ChunkGeneration.java` | 450 | +| `ChunkRegistry.java` | 402 | +| `LazySectionBlockStorage.java` | 389 | +| `BlockWriter.java` | 380 | +| `ChunkPersistence.java` | 262 | +| `ChunkLifecycleListener.java` | 239 | +| `BlockStorage.java` | 238 | +| `SectionBlockStorage.java` | 213 | +| `PaletteCompaction.java` | 212 | +| `net/minestom/server/instance/ChunkViewerCache.java` | 96 | +| `FalcoInstanceException.java` | 58 | +| `package-info.java` | 46 | +| `ChunkLifecycleEvent.java` | 32 | + +`FalcoInstance` went from **1 721 lines to 951**, a fall of 770, and it now declares exactly four +fields — `registry`, `blockWriter`, `persistence`, `lifecycle` — with `InstanceFacadeTest` failing +when a fifth appears. Beside it, nine new main-source files hold **2 611 lines** — eight in +`falco-instance`, one (`ChunkLightListener`) in `falco-light` — and `FalcoChunk` grew from 948 to +1 115 for the five notification points. The whole of `falco-instance/src/main/java` went from 3 825 +to 5 715 lines. + +**That is the weakest number of this stage and it belongs here.** Behaviour did not change; the +module is 1 890 lines larger for it. **1 657 of the 2 611 new lines — 63 % — are Javadoc**, counted +rather than estimated, because the extracted classes had to write down rules that used to be +implicit in one file: what a step handed inside the position lock may do, how far the chunk write +lock reaches, which of the two instance arms is the stricter one to write a lifecycle listener for. +The remaining 954 lines are the price of naming things — five responsibilities that were `private` +methods sharing fields are now five classes with parameters and return types. + +What the stage bought is not in this table. It is that `FalcoChunk` can carry a lifecycle listener at +all, which is what made US-3.06 possible — `FalcoLightingChunk extends FalcoChunk`, so one chunk +object now carries both the lifecycle and the light, where two classes used to have to be paired by +hand. That was the structural reason the whole undertaking existed, and it is not a line count. + +### What stage 3 did not achieve + +**The tick race is still open.** `FalcoChunk#tick(long)` iterates `entries` with no lock while the +tick thread holds only its own, so a concurrent `setBlock` that rehashes the map can make the walk +yield garbage. Upstream `DynamicChunk` has the identical race with its `tickableMap`, so it is +inherited rather than introduced — but this stage owns the lifecycle and did not fix it, and ArchUnit +cannot see it, because the field is `final` and `sharedStateIsSafelyPublished` skips it by +construction. It is recorded in `docs/superpowers/HANDOFF-instance-chunk.md` under *Open defect*. + +**The demo does not run its Falco stack on a `FalcoInstance`.** The definition of done asks for it. +Task 10 changed the prose and `ServerStack#note()` instead and left the demo on an +`InstanceContainer`, because switching it would have put a third variable into a two-stack +comparison. The combination is pinned by `FalcoStackIntegrationTest#testTheStackNeedsNoLifecyclePairAnyMore` +rather than demonstrated by the demo, which is a weaker form of the same claim. + +**The primitive chunk map is not free of costs, only of that one allocation.** `size()` and `idle()` +do not read a counter: both call the library's `promote()` first, which takes the map's monitor and +swaps the read map whenever the map is amended, and only then walk the read map — so they are linear +*and* on a lock where they used to be constant and lock free. Harmless in this codebase, because they +are reached from `unregister` and a log line and never from a tick, but it is a change and it is on +the class. `chunks()` builds a fresh view object per call, because the fastutil base class does not +cache one the way `ConcurrentHashMap` does. + +**The lookup path is not unconditionally lock free either, and the first version of this section said +it was.** `Long2ObjectSyncMapImpl#getEntry` (flare-fastutil 2.0.1, lines 137-151) reads the read map +without a lock, and when that returns null while the map is `amended` it enters +`synchronized(this.lock)` and consults the dirty map. `amended` is set by any `put` of a key the read +map does not hold — that is every chunk load — and is only cleared by a promotion, which needs as +many misses as the dirty map has entries. So after n loads the monitor is on the miss path for up to +n misses, and the miss path is taken for keys that are absent altogether, not only for keys sitting +in the dirty map: `FalcoInstance#getChunk` returning null for an unloaded position is exactly that +call. This is a documentation defect rather than a measured regression — `ChunkLookupBenchmark` walks +keys that are present and prices the hit path, so no figure of this repository prices the miss path +in either direction. That is precisely why the field javadoc now names it instead of asserting it +away, and why `ChunkMapLockOnMissTest` pins it: the claim is about a dependency, so nothing here +would have failed when flare or the Minestom bump behind it changes. It does not touch NFR-006: this +monitor guards one map, where the monitor of `InstanceContainer` is the instance and is held across +handlers, packets and events. + +**The module edge from `falco-light` to `falco-instance` is a cost, not a win.** It reverses the +argument the old `FalcoLightingChunk` javadoc made, and it is paid so that one chunk can be both +things. `compileOnly` and the ArchUnit rule that keeps it to the two classes that need it are the +containment, not a cancellation. + +**`ChunkViewerCache` still splits a package with Minestom.** `net.minestom.server.instance` is the +only place from which the tracker's cache is reachable at all. On the classpath, where every consumer +runs today, that is invisible; on the module path it is fatal, and it stays fatal until Minestom +exposes a way to release an entry. + +**The container's own viewer cache growth (M14) is untouched**, because it cannot be reached from +outside Minestom. `ChunkViewerCacheLeakTest` keeps measuring it as the reason the Falco side was +worth cleaning up. + +**The stage widened an architecture rule.** `space.vectrix.flare..` joined the allowlist of +`publishedModulesOnlyUseDeclaredDependencies`, which had gone red with eleven violations. Both halves +of the justification were checked rather than assumed — the published POM lists `slf4j-api` and +nothing else, and Minestom brings flare 2.0.1 to every runtime classpath while hiding it from its own +compile classpath — and the rule was proven still to bite afterwards with a +`javax.xml.namespace.QName`. It is still one allowed package more than the stage started with, and +the version pin it rests on has to move with the next Minestom bump. + +`:falco-instance:javadoc`, `:falco-light:javadoc` and `:falco-anvil:javadoc` pass with `-Werror`. + +### What the closing review of the stage changed, after the numbers above were taken + +Two findings of the closing review are fixed in `9ec302a2` and `770301cb`, and both of them make a +sentence of this section older than the code it describes. They are booked here rather than edited +into the tables above, because every figure above was measured at `bf4b4e29` and is still what that +commit had. + +**A throwing lifecycle listener used to hang a chunk load, and this section counted the notification +points without asking what a throw out of one costs.** Stage 3 put third-party code between the chunk +being ready and its future being completed — `publish` ends in `FalcoChunk#notifyPublished`, +`notifyLoaded` ends in `ChunkLifecycleListener#onLoad`, the refused arm ends in `onUnload` — and all +three sat outside the try/catch of `ChunkLifecycle#completeLoad`, which covers only the production of +the chunk. A throw therefore left the future uncompleted: every `loadChunk(x, z).join()` on that +position waited for the life of the process, while the chunk sat in the registry with a tick +partition and no `InstanceChunkLoadEvent`. The trigger is in this repository, not hypothetical — +`ChunkLightListener#onLoad` reaches `ChunkLightScheduler#bind`, which throws when one scheduler is +asked to serve two instances, which is exactly the pairing US-3.06 made possible. The stretch is now +wrapped: the throwable is handed to the waiting callers and rethrown unchanged, so an +`InstanceContainer`'s loud failure stays loud and only the hang is gone. + +**The lock reach of `BlockWriter` was one entry short in its own class documentation.** It enumerated +three pieces of foreign code under the chunk write lock and called naming them the honest thing to +do; since `83825cc8` there were four, because `FalcoChunk#setBlock` ends in +`listener.onBlockChange(...)` with the caller still holding that lock. It is the only one of the four +a third party installs without touching a block, so the audit that starts at the class owning the +lock could not find it. Nothing about the behaviour changed; the count, the re-entrancy hazard and +the `write` javadoc did, and `BlockWriterTest` now reads `holdsWriteLock()` from inside +`onBlockChange` the way it already did from inside the other three. + +The counts this moves: + +| | at `bf4b4e29` | now | what moved | +| --- | ---: | ---: | --- | +| `:falco-instance:` tests | 220 | **225** | +4 this wave, +1 the lookup-lock wave (`721a18ce`) | +| `ChunkLifecycle.java` | 632 | **678** | the wrapped stretch and what it costs a listener | +| `ChunkLifecycleListener.java` | 239 | **258** | what a throw costs, per arm, on both instance arms | +| `BlockWriter.java` | 380 | **400** | the fourth piece of foreign code under the lock | +| `ChunkRegistry.java` | 402 | **431** | `721a18ce`, not this wave | +| `falco-instance/src/main/java` | 5 715 | **5 829** | 85 of the 114 are this wave, all of them Javadoc | + +The other five suites are unchanged at 210 / 43 / 217 / 42 (1 skipped) / 167, all green, and +`:falco-instance:javadoc` and `:falco-light:javadoc` still pass with `-Werror`. + +### The gate itself, re-taken at the last commit of the stage + +Everything above was measured at `bf4b4e29` or reported per wave afterwards. The stage may only be +called done against the commit it actually ends at, so the whole set was run once more at `87ffd652`: + +| module | tests | failures | errors | skipped | +| --- | ---: | ---: | ---: | ---: | +| `:falco-instance:` | 225 | 0 | 0 | 0 | +| `:falco-anvil:` | 217 | 0 | 0 | 0 | +| `:falco-light:` | 210 | 0 | 0 | 0 | +| `:falco-demo:` | 167 | 0 | 0 | 0 | +| `:falco-benchmarks:` | 42 | 0 | 0 | 1 | +| `:falco-archunit:` | 43 | 0 | 0 | 0 | + +Counted out of the JUnit XML rather than read off the console, together with `:falco-instance:`, +`:falco-light:` and `:falco-anvil:javadoc` under `-Werror`. No count fell against any earlier column. + +**That run was not made in the stage's own worktree, and the reason is a finding rather than a +footnote.** Two attempts there failed — the first with `java.io.EOFException` on two test +tasks, the second with `java.nio.file.NoSuchFileException` on +`build/test-results/test/binary/in-progress-results-generic.bin`, the same two tasks — and neither +failure was an assertion: the second attempt logged 251 `PASSED` lines and no test-level failure at +all, and the four suites that did finish in the first attempt wrote 0 failures and 0 errors into +their XML. A second session was running Gradle against the same project directory and +removing `build/` underneath the run, and the load average moved from 1.5 to 19.7 across it. A green +run in a directory a second writer is clearing is not evidence of anything, so the acceptance was +taken in a worktree detached at `87ffd652` and removed afterwards, which is the same precaution the +lookup-lock wave had to take. + +**The gate was then attacked, because an acceptance which cannot fail measures nothing.** Two +mutations, both against the two claims of the definition of done that carry the most weight, each +reverted afterwards: + +| mutation | result | +| --- | --- | +| a fifth field on `FalcoInstance` (`private final Object mutationProbe = new Object();`) | **killed** — `InstanceFacadeTest > declares exactly the four parts it delegates to` | +| `ChunkViewerCache.release(...)` removed from `ChunkLifecycle#unload` | **killed** — `ChunkViewerCacheTest > leaves the cache where it found it across a load and an unload` | + +The second one is the more informative of the two: its three sibling cases stayed green under the +same mutation, so the cycle assertion is the only thing in that class which sees the release at all. + +**What neither fix repairs.** A listener which throws on the publish or the load arm still leaves a +chunk in the registry that every later caller is handed while this one load was reported as failed. +That is not a state this class can undo — the chunk got its tick partition inside the position lock, +long before the listener ran — and it is now stated on `completeLoad` and on both listener methods +rather than left to be discovered. The rule remains that a lifecycle listener does not throw. diff --git a/docs/superpowers/plans/2026-08-02-falco-lazy-sections.md b/docs/superpowers/plans/2026-08-02-falco-lazy-sections.md new file mode 100644 index 0000000..b01df27 --- /dev/null +++ b/docs/superpowers/plans/2026-08-02-falco-lazy-sections.md @@ -0,0 +1,2544 @@ +# Falco Lazy Sections — Stage 2 Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Make the chunk cost what its terrain costs. Stage 1 built the seam and proved it free; it removed nothing. This stage puts a layout behind that seam which holds no `Section` for a section that is nothing but air, holds no heightmap until something asks for one, holds one block map instead of two, and calls `optimize()` on the palettes a generator filled — and it measures every one of those against the figures stage 1 left behind. + +**Architecture:** A flyweight one level above `Section`. Every empty slot of `LazySectionBlockStorage` points at one process-wide `EMPTY` section; the first write to a slot replaces it with a fresh one. The flyweight can be neither a `Section` nor a `Palette` — `Section` is a `record` and therefore final, and `Palette` is `public sealed interface Palette permits PaletteImpl`, closed by the verifier — so it lives in `BlockStorage`, which is exactly the seam stage 1 bought. The interface grows a second, non-materialising way to look at a section, because the difference between a caller that reads a section and a caller that may write to it is the difference between a saving that survives and one that does not. + +**Tech Stack:** Java 25, Gradle, JUnit 5, Cyano (Minestom test extension), JMH + JOL for measurement, fastutil. + +## Global Constraints + +Copied verbatim from the spec (`docs/superpowers/specs/2026-08-01-falco-instance-chunk-design.md`, §7): + +- **NFR-001** — The modules shall compile and run against the pinned Minestom version without reflection, `--add-opens` or an open module. +- **NFR-002** — The modules shall use only language and JDK features that are final in Java 25; no preview and no incubator feature shall be required to build or run. +- **NFR-003** — If a performance claim is published, then shall a JMH or JOL measurement in this repository support it, stated with its conditions. +- **NFR-004** — While a comparison benchmark runs, shall it fail rather than report a number if the two sides disagree on their result. +- **NFR-005** — When a chunk read fails, shall the failure reach the caller instead of being reported as an absent chunk. +- **NFR-006** — While a block is written, shall the lock held be the lock of the chunk it touches, not a monitor over the instance. +- **NFR-007** — The chunk shall allocate no object per block read on any path. +- **NFR-008** — The chunk shall not require `-XX:+UseCompactObjectHeaders`; where the flag helps, the gain shall be stated per class and measured, never as a percentage. +- **NFR-009** — Every new public type shall carry `@ApiStatus.Experimental` while the module is experimental. + +Repository conventions, non-negotiable: + +- **Source and Javadoc are English**, and Javadoc *justifies* decisions in `

` paragraphs and `

` sections. Every type carries `@author TheMeinerLP`, `@version`, `@since 0.4.0`. **Changing an existing class raises its `@version`.** Model: `falco-light/src/main/java/net/onelitefeather/falco/light/ChunkLightService.java`. +- **Gradle files stay comment-free.** +- **Minestom reference is the pinned sources jar**, unpacked at `/tmp/claude-1000/-mnt-projects-oss-onelitefeather-Falco/34edb948-9dfe-4540-9666-9e29f0d44d7b/scratchpad/minestom-src/`. The clone at `/mnt/projects/oss/minestom/Minestom` is ten months stale and must not be used. +- Work happens in the worktree `/mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage`, on branch `feat/block-storage`. Every Gradle command is prefixed with `cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage &&`, because the working directory of a shell call does not persist. +- **Measured, not asserted.** No figure without its conditions, no green test that claims instead of checking. + +## The measured starting point + +Everything below is from the `Stage 1 result` section of `docs/superpowers/plans/2026-08-01-falco-block-storage.md` and from §2 of the spec. Legacy object headers of twelve bytes, eight byte alignment, JOL through the instrumentation agent, JDK 25.0.3 (Temurin). A number from a `-XX:+UseCompactObjectHeaders` run must never be quoted next to one of these. + +| # | What | Figure | Where it came from | +|---|---|---|---| +| S1 | A fresh `DynamicChunk` | 192 objects, 6 848 B | `ChunkFootprintTest` | +| S2 | A fresh `FalcoChunk` after stage 1 | 193 objects, 6 872 B | `ChunkFootprintTest` | +| S3 | — of the fresh chunk, the section list and everything below it | 5 128 B, **74.9 %** | `ChunkFootprintTest` breakdown | +| S4 | — of the fresh chunk, both heightmaps with their two `short[256]` | 1 120 B, **16.4 %** | `ChunkFootprintTest` breakdown | +| S5 | — of the fresh chunk, the 48 `AtomicBoolean` | 768 B, 11.2 % | `ChunkFootprintTest` breakdown | +| S6 | Sharing empty sections instead of allocating 24, at construction | **2 104 against 7 096 B/op, −70 %** | `LazySectionBenchmark#buildSectionsLazy` against `#buildSectionsMinestom` | +| S7 | Empty section share of a generated overworld, finished chunks only | **62.24 %**, 441 chunks around one spawn | `EmptySectionCensusTest` | +| S8 | Flyweight saving at that share | **2 911 B per chunk**, 11.4 MB over 4 096 chunks | JOL, `EmptySectionCensusTest#testTheFootprintOfBothSectionLayouts` | +| S9 | A generated chunk stays at 15 bpe direct | **203 840 against 84 800 B**, factor 2.4 | JOL; `optimize()` has no caller in Minestom's main tree | + +`LazySectionBenchmark` is not a benchmark this stage has to write. It already measures precisely the candidate of this stage, down to the reason the materialisation allocates instead of cloning, and its `LazySections` prototype is the shape `LazySectionBlockStorage` has to take. Read it before Task 2 and reproduce its decisions rather than re-deriving them. + +## Four traps, verified against the pinned sources before they were written down + +**The flyweight cannot be a `Section` and cannot be a `Palette`.** `Section.java:6` is `public record Section(Palette blockPalette, Palette biomePalette, Light skyLight, Light blockLight)`, and a record is final. `Palette.java:29` is `public sealed interface Palette permits PaletteImpl`. Neither a lazy section nor a lazy palette can be handed to Minestom, so the pattern lives one level above both, in `BlockStorage`. That is not a workaround; it is the reason stage 1 existed. + +**Materialise with `new Section()`, never with `EMPTY.clone()`.** `Section#clone` builds two fresh carriers and then calls `skyLight.set(this.skyLight.array())` and `blockLight.set(this.blockLight.array())`. For the flyweight, `array()` returns `LightCompute.UNSET_CONTENT`, and `SkyLight#set` runs `this.content = lazyArray(copyArray)` — and `LightCompute#lazyArray` answers a zero-length array with `EMPTY_CONTENT`, the shared static `byte[2048]`. `set` then also sets `isValidBorders = true`, `contentPropagation = content` and `needsSend.set(true)`. A section materialised by cloning would therefore report that it has light to send when it has never been lit, and would point its `content` field at a process-wide mutable array shared with every other section materialised the same way. `new Section()` leaves `content` null and `needsSend` false, allocates no light array, and is what `LazySectionBenchmark#firstWriteLazy` measured at 2 720 B/op. + +**`getSections()` and `getSection(int)` are the boundary, and the heightmap of Minestom walks through it.** Their callers in the pinned sources are `InstanceContainer#generateChunk` (`:413`, `:415`, writes), `AnvilLoader#loadSections` (`:214`, writes) and `AnvilLoader#saveChunk` (`:423`, reads), `LightingChunk` (`:136`, `:188`, `:204`, `:373`, `:385`, `:392`, `:459`, `:526`), `Instance#invalidateSection` (`:311`), and — the one that decides this stage — `Heightmap#refresh(int,int,int)` (`:77`) and `Heightmap#getHighestBlockSection` (`:134`). The second of those walks the chunk **from the top downwards** calling `chunk.getSection(sectionY).blockPalette()` until it meets a palette whose `count()` is not zero. Those are exactly the empty top sections the flyweight exists to avoid. `FalcoChunk#setBlock` reaches it through `calculateFullHeightmap()` on the first write, and `createChunkPacket` reaches it through `getHeightmaps()` on the first send. Left alone, one `setBlock` into a fresh chunk would materialise all twenty-four sections and this stage would save nothing at all. In the repository the same boundary is crossed by `FalcoInstance#applyGenerator:923` (`getSections()`, writes every palette), `FalcoInstance#applyFork:1047` (`getSectionAt`, writes), `FalcoAnvilLoader:1053` and `:1161`, and `ChunkLightService:160` and `:405`. + +**The stage 1 footprint assertion has to be replaced, and replaced with something at least as sharp.** `ChunkFootprintTest#assertTheSeamIsTheOnlyDifference` currently demands that `FalcoChunk` and `DynamicChunk` retain identical objects and bytes in every class except `SectionBlockStorage`, of which Falco holds exactly one. Every task below breaks that by construction. Task 9 replaces it with a declared, per-class difference table, not with a tolerance. A tolerance of the form "at most N bytes" is rejected: it is what the equality existed to prevent. + +## File Structure + +| File | Responsibility | +|---|---| +| `falco-instance/src/main/java/net/onelitefeather/falco/instance/BlockStorage.java` | **Modify.** Gains `view(int)`, `views()`, `shared(int)` and `materialisedSections()` — the non-materialising counterpart of the boundary methods, and the counter that makes the saving assertable. `@version 1.1.0` → `2.0.0`. | +| `.../instance/SectionBlockStorage.java` | **Modify.** Implements the four new members trivially; it shares nothing and materialises nothing, so every one of them is a constant answer. `@version 1.1.0` → `1.2.0`. | +| `.../instance/LazySectionBlockStorage.java` | **Create.** The flyweight storage. One process-wide `EMPTY`, copy on first write, `new Section()` and never `EMPTY.clone()`. | +| `.../instance/FalcoChunk.java` | **Modify.** Defaults to the lazy storage; routes its own packet, light and snapshot reads through `views()`; computes the highest non-empty section itself instead of through `Heightmap#getHighestBlockSection`; builds its heightmaps on demand; drops `tickableMap`. `@version 2.1.0` → `3.0.0`. | +| `.../instance/FalcoInstance.java` | **Modify.** `applyGenerator` commits only the sections a generator actually filled and calls `Palette#optimize` on them; `applyFork` skips a fork section that carries nothing. `@version` raised. | +| `falco-instance/src/test/java/.../instance/BlockStorageTest.java` | **Modify.** Becomes parameterised over both implementations, which is the promise stage 1 made when it wrote the contract tests against the interface. | +| `falco-instance/src/test/java/.../instance/LazySectionBlockStorageTest.java` | **Create.** The properties only the flyweight has: identity of the shared slot, materialisation of exactly one section, air and biome writes that must not materialise, `copy` that keeps sharing. | +| `falco-instance/src/test/java/.../instance/SectionMaterialisationTest.java` | **Create.** Counts what each boundary caller actually materialises. This is the acceptance test of the whole stage. | +| `falco-benchmarks/src/jmh/java/.../benchmark/instance/GeneratorCommitBenchmark.java` | **Create.** Prices `Palette#optimize` in time against the generation it follows, because S9 states its byte saving and nothing states its cost. | +| `falco-benchmarks/src/test/java/.../benchmark/instance/ChunkFootprintTest.java` | **Modify.** The seam assertion becomes a declared per-class difference table. `@version 1.1.0` → `2.0.0`. | + +Already in `falco-benchmarks` and **not to be reinvented**: `LazySectionBenchmark` (the candidate of this stage, with the axis at 0/62/90 percent empty), `SectionAllocationBenchmark` (what the posts of a chunk cost at construction), `EmptySectionCensusTest` (S7 and S8), `ChunkFootprintTest` (S1–S5), `PaletteFootprintTest` (the palette side of S9), `ChunkComparisonBenchmark` and `FalcoChunkEquivalenceTest` (the regression net, and the evidence for US-1.03). All of them must be re-run at the end of the stage. + +--- + +### Task 1: A way to look at a section without creating one + +**Files:** +- Modify: `falco-instance/src/main/java/net/onelitefeather/falco/instance/BlockStorage.java` +- Modify: `falco-instance/src/main/java/net/onelitefeather/falco/instance/SectionBlockStorage.java` +- Test: `falco-instance/src/test/java/net/onelitefeather/falco/instance/BlockStorageTest.java` + +**Interfaces:** +- Consumes: `BlockStorage`, `SectionBlockStorage` as stage 1 left them. +- Produces: `Section BlockStorage#view(int section)`, `List
BlockStorage#views()`, `boolean BlockStorage#shared(int section)`, `int BlockStorage#materialisedSections()`. Tasks 2, 3, 6 and the tests of Tasks 4 and 9 depend on exactly these names and on the index being an offset from the bottom section, as `section(int)` already is. + +**Why this is a task of its own.** `sections()` and `section(int)` are wired to `Chunk#getSections()` and `Chunk#getSection(int)`, which hand a `Section` to a stranger who may write into it, so they have to materialise (US-2.09). Every read `FalcoChunk` performs on its own sections — the chunk packet, the light data, the highest-section scan — is not such a stranger, and routing it through the same method would undo the saving from inside the chunk. The seam therefore needs both, and the difference between them has to be a documented contract rather than a habit. + +- [ ] **Step 1: Write the failing test** + +Append to `BlockStorageTest.java`. It is written against the interface, so Task 2's implementation inherits it unchanged: + +```java + @Test + @DisplayName("reports every section as materialised when it holds one of its own") + void testEagerStorageSharesNothing() { + final BlockStorage storage = storage(); + + assertEquals(SECTIONS, storage.materialisedSections()); + for (int section = 0; section < SECTIONS; section++) { + assertFalse(storage.shared(section), + "section " + section + " of an eager storage cannot be shared"); + } + } + + @Test + @DisplayName("hands out the same section through the view as through the boundary") + void testViewAndSectionAgree() { + final BlockStorage storage = storage(); + + storage.setBlock(1, 2, 3, Block.STONE); + + assertSame(storage.section(0), storage.view(0), + "an eager storage has nothing to materialise, so the two accessors are one"); + assertEquals(SECTIONS, storage.views().size()); + for (int section = 0; section < SECTIONS; section++) { + assertSame(storage.sections().get(section), storage.views().get(section), + "the view of section " + section + " has to be the section itself"); + } + } + + @Test + @DisplayName("keeps the view in step with what was written after it was handed out") + void testViewFollowsLaterWrites() { + final BlockStorage storage = storage(); + final List
views = storage.views(); + + storage.setBlock(1, 2, 3, Block.STONE); + + assertEquals(Block.STONE.stateId(), views.get(0).blockPalette().get(1, 2, 3), + "a view that was taken before a write has to show the write, or a caller which " + + "holds one is reading a chunk that no longer exists"); + } +``` + +New imports for the test file: `net.minestom.server.instance.Section`, `java.util.List`, `org.junit.jupiter.api.Assertions.assertFalse`, `org.junit.jupiter.api.Assertions.assertSame`. + +- [ ] **Step 2: Run the test to verify it fails** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +./gradlew :falco-instance:test --tests "*BlockStorageTest*" +``` + +Expected: compilation failure — `view`, `views`, `shared` and `materialisedSections` do not exist on `BlockStorage`. + +- [ ] **Step 3: Add the four members to the interface** + +Insert into `BlockStorage.java`, after `sectionCount()`: + +```java + /** + * Hands out one section of this storage as it stands, without creating one. + *

+ * This is the read-only counterpart of {@link #section(int)} and the difference between the two + * is the whole economy of a lazy layout. {@link #section(int)} exists to answer + * {@code Chunk#getSection(int)}, which gives a {@code Section} to a caller this storage knows + * nothing about — a chunk loader, the light engine of Minestom, the generator of an + * {@code InstanceContainer} — and every one of those may write into it, so the slot has to hold a + * section of its own before it is handed over. This method promises the opposite: the caller only + * reads, so an implementation which shares one section between every empty slot may hand that + * shared section out instead of creating a private one. + *

+ *

+ * The contract that comes with it is therefore sharp, and violating it corrupts more than one + * chunk: the returned section must not be written to, neither through its + * palettes nor through its light carriers, and it must not be kept beyond the call. A write + * through a shared section is not a write to this chunk, it is a write to every chunk in the + * process whose slot at that height happens to be empty. + *

+ *

+ * The section a view answers with is always the one the storage currently holds, so a view taken + * before a write shows the write. An implementation must not answer from a snapshot. + *

+ * + * @param section the index of the section, counted from the bottom one + * @return the section as it stands, which may be shared with other chunks + */ + Section view(int section); + + /** + * Hands out the sections of this storage as they stand, without creating any. + *

+ * The same contract as {@link #view(int)}, over the whole chunk: read only, do not keep, and + * expect a shared section wherever the chunk holds nothing. An implementation is expected to + * answer with a list it owns rather than with a fresh one, because this is the method the packet + * builder of a chunk walks, and a list allocated per send is a cost this stage exists to remove + * rather than to add. + *

+ * + * @return the sections as they stand, from the bottom one upwards + */ + List
views(); + + /** + * Reports whether a section is still shared with other chunks rather than owned by this one. + *

+ * The question a caller which is about to write needs answered without triggering the write it is + * asking about. {@code FalcoInstance} uses it to decide whether a generated section is worth + * committing at all, and the tests of this stage use it to prove that a saving happened rather + * than assuming it. + *

+ * + * @param section the index of the section, counted from the bottom one + * @return whether the slot still points at a section this storage does not own + */ + boolean shared(int section); + + /** + * Reports how many sections this storage owns rather than shares. + *

+ * The one number that makes the whole stage assertable. Every claim about a saving is a claim + * about this counter, and every boundary method that materialises raises it, so a test can state + * exactly what a chunk send, a generator run or a save costs instead of estimating it. + *

+ * + * @return the amount of sections this storage holds of its own, between zero and + * {@link #sectionCount()} + */ + int materialisedSections(); +``` + +Raise the class Javadoc to `@version 2.0.0` and add a section to it explaining the split, in the style the file already uses: + +```java + *

Two ways to reach a section, and why that is not one too many

+ *

+ * {@link #section(int)} and {@link #sections()} answer {@code Chunk#getSection(int)} and + * {@code Chunk#getSections()}, which are public methods of Minestom that hand a {@code Section} to + * an arbitrary caller. A storage cannot know whether such a caller reads or writes, so those two + * have to produce a section the chunk owns. {@link #view(int)} and {@link #views()} are for the + * chunk itself, which does know: its packet builder, its light data builder and its heightmap scan + * only read. Without the second pair a lazy layout would be undone from inside the very class that + * chose it, on the first packet a chunk sends. + *

+``` + +- [ ] **Step 4: Implement the four members in `SectionBlockStorage`** + +Append to `SectionBlockStorage.java`, after `sectionCount()`: + +```java + @Override + public Section view(int section) { + return section(section); + } + + @Override + public List
views() { + return this.sections; + } + + @Override + public boolean shared(int section) { + return false; + } + + @Override + public int materialisedSections() { + return this.sections.size(); + } +``` + +Raise the class Javadoc to `@version 1.2.0` and add one paragraph saying why all four are constant answers here: + +```java + *

+ * The four members that exist for a lazy layout are constant answers in this one. Every section is + * allocated in the constructor, so nothing is ever shared and nothing is ever materialised: a view + * is the section, {@code shared} is always false and {@code materialisedSections} is the section + * count. That is not a stub — it is what makes this class usable as the eager control in every + * comparison of the next stage, and it is why the same interface can describe both layouts without + * either of them carrying a flag about which one it is. + *

+``` + +- [ ] **Step 5: Run the test** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +./gradlew :falco-instance:test --tests "*BlockStorageTest*" +``` + +Expected: PASS, including the three new cases. + +- [ ] **Step 6: Commit** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +git add falco-instance/src/main/java/net/onelitefeather/falco/instance/BlockStorage.java \ + falco-instance/src/main/java/net/onelitefeather/falco/instance/SectionBlockStorage.java \ + falco-instance/src/test/java/net/onelitefeather/falco/instance/BlockStorageTest.java +git commit -m "feat(instance): give the storage a read-only way to look at a section" +``` + +--- + +### Task 2: `LazySectionBlockStorage`, the flyweight + +**Files:** +- Create: `falco-instance/src/main/java/net/onelitefeather/falco/instance/LazySectionBlockStorage.java` +- Modify: `falco-instance/src/test/java/net/onelitefeather/falco/instance/BlockStorageTest.java` +- Create: `falco-instance/src/test/java/net/onelitefeather/falco/instance/LazySectionBlockStorageTest.java` + +**Interfaces:** +- Consumes: `BlockStorage` from Task 1. +- Produces: `LazySectionBlockStorage(int minSection, int sectionCount)` and `LazySectionBlockStorage(int minSection, List
sections)`. Task 3 constructs the first, Task 6 reads through `view`/`shared`/`section`. + +**Reference:** `LazySectionBenchmark.LazySections` in `falco-benchmarks` is the prototype of this class and its Javadoc carries the reasoning that was already measured. Read it first. The differences are that this class also carries biomes, the section index offset and the copy semantics, and that it lives where a chunk can use it. + +**Covers:** US-2.01, US-2.02, US-2.07, US-2.09. + +- [ ] **Step 1: Write the failing test** + +Create `LazySectionBlockStorageTest.java`: + +```java +package net.onelitefeather.falco.instance; + +import net.minestom.server.MinecraftServer; +import net.minestom.server.instance.Section; +import net.minestom.server.instance.block.Block; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNotSame; +import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertTrue; + +@DisplayName("The lazy block storage of a chunk") +class LazySectionBlockStorageTest { + + private static final int SECTIONS = 24; + private static final int MIN_SECTION = -4; + + @BeforeAll + static void server() { + if (MinecraftServer.process() == null) { + MinecraftServer.init(); + } + } + + private static LazySectionBlockStorage storage() { + return new LazySectionBlockStorage(MIN_SECTION, SECTIONS); + } + + @Test + @DisplayName("owns no section at all before anything is written") + void testNothingIsMaterialisedUpFront() { + final LazySectionBlockStorage storage = storage(); + + assertEquals(0, storage.materialisedSections()); + for (int section = 0; section < SECTIONS; section++) { + assertTrue(storage.shared(section), "section " + section + " has to start out shared"); + } + } + + @Test + @DisplayName("shares one and the same section between every empty slot and every chunk") + void testEverySharedSlotIsTheSameObject() { + final LazySectionBlockStorage first = storage(); + final LazySectionBlockStorage second = storage(); + final Section shared = first.view(0); + + for (int section = 0; section < SECTIONS; section++) { + assertSame(shared, first.view(section)); + assertSame(shared, second.view(section)); + } + } + + @Test + @DisplayName("materialises exactly the section that was written to and leaves the others shared") + void testAWriteMaterialisesOneSection() { + final LazySectionBlockStorage storage = storage(); + + storage.setBlock(1, 20, 3, Block.STONE); + + assertEquals(1, storage.materialisedSections()); + assertFalse(storage.shared(1), "y=20 belongs to section index 1 of a chunk starting at -64"); + for (int section = 0; section < SECTIONS; section++) { + if (section == 1) continue; + assertTrue(storage.shared(section), "section " + section + " was not written to"); + } + assertEquals(Block.STONE, storage.getBlock(1, 20, 3, Block.Getter.Condition.NONE)); + assertEquals(Block.AIR, storage.getBlock(1, 36, 3, Block.Getter.Condition.NONE)); + } + + @Test + @DisplayName("does not materialise a section that is written air, but does for cave air") + void testWritingAirLeavesTheSlotShared() { + final LazySectionBlockStorage storage = storage(); + + storage.setBlock(1, 20, 3, Block.AIR); + + assertEquals(0, storage.materialisedSections(), + "writing the state the shared section already holds everywhere changes nothing, and " + + "a loader that walks a whole chunk writing air would otherwise materialise " + + "every section it touched"); + + storage.setBlock(1, 20, 3, Block.CAVE_AIR); + + assertEquals(1, storage.materialisedSections(), + "cave air is a different state id from air and has to be stored"); + assertEquals(Block.CAVE_AIR, storage.getBlock(1, 20, 3, Block.Getter.Condition.NONE)); + } + + @Test + @DisplayName("answers a read of a shared section without touching a palette") + void testReadingASharedSectionDoesNotMaterialise() { + final LazySectionBlockStorage storage = storage(); + + for (int y = -64; y < 320; y += 16) { + assertEquals(Block.AIR, storage.getBlock(0, y, 0, Block.Getter.Condition.NONE)); + } + assertEquals(0, storage.materialisedSections()); + } + + @Test + @DisplayName("materialises every section when the boundary hands them out") + void testTheBoundaryMaterialisesEverything() { + final LazySectionBlockStorage byOne = storage(); + final LazySectionBlockStorage byAll = storage(); + + byOne.section(5); + assertEquals(1, byOne.materialisedSections(), + "section(int) is the boundary for one section, not for the chunk"); + + byAll.sections(); + assertEquals(SECTIONS, byAll.materialisedSections(), + "sections() hands the whole chunk to a caller that may write to any of it"); + } + + @Test + @DisplayName("materialises with a fresh section rather than a clone of the shared one") + void testMaterialisationDoesNotCloneTheFlyweight() { + final LazySectionBlockStorage storage = storage(); + final Section shared = storage.view(0); + + storage.setBlock(0, 0, 0, Block.STONE); + final Section materialised = storage.view(4); + + assertSame(shared, materialised, "y=0 is section index 4, which was not written to"); + + final Section written = storage.view(4 + 0); + assertNotSame(shared, storage.view(4), "guard against the fixture drifting"); + assertEquals(0, written.skyLight().array().length, + "a materialised section has no light; Section#clone would have installed " + + "LightCompute.EMPTY_CONTENT through SkyLight#set and raised needsSend"); + assertFalse(written.skyLight().requiresSend(), + "a section that has never been lit has nothing to send"); + } + + @Test + @DisplayName("copies without materialising what the original had not materialised") + void testCopyKeepsSharing() { + final LazySectionBlockStorage original = storage(); + original.setBlock(1, 20, 3, Block.STONE); + + final BlockStorage copy = original.copy(); + + assertEquals(1, copy.materialisedSections()); + assertEquals(Block.STONE, copy.getBlock(1, 20, 3, Block.Getter.Condition.NONE)); + + copy.setBlock(1, 20, 3, Block.DIRT); + assertEquals(Block.STONE, original.getBlock(1, 20, 3, Block.Getter.Condition.NONE), + "a copy that shared a materialised section would change the original"); + } + + @Test + @DisplayName("returns every slot to the shared section when it is cleared") + void testClearReleasesEverySection() { + final LazySectionBlockStorage storage = storage(); + storage.setBlock(1, 20, 3, Block.STONE); + final Section materialised = storage.view(1); + + storage.clear(); + + assertEquals(0, storage.materialisedSections()); + assertEquals(Block.AIR, storage.getBlock(1, 20, 3, Block.Getter.Condition.NONE)); + assertEquals(0, materialised.blockPalette().count(), + "a caller holding the section from before the reset has to see it emptied, which is " + + "what Section#clear does and what DynamicChunk#reset relies on"); + } +} +``` + +The eighth test is deliberately awkward and has to stay that way: it asserts a property of the *materialised* section, which is only reachable through a view of the slot that was written. Fix the indices when writing it so that the section under assertion really is the written one — `y = 0` is index `4` for a chunk whose bottom section is `-4`. + +- [ ] **Step 2: Run the test to verify it fails** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +./gradlew :falco-instance:test --tests "*LazySectionBlockStorageTest*" +``` + +Expected: compilation failure — `LazySectionBlockStorage` does not exist. + +- [ ] **Step 3: Write the implementation** + +Create `LazySectionBlockStorage.java`: + +```java +package net.onelitefeather.falco.instance; + +import net.minestom.server.MinecraftServer; +import net.minestom.server.coordinate.CoordConversion; +import net.minestom.server.instance.Section; +import net.minestom.server.instance.block.Block; +import net.minestom.server.registry.DynamicRegistry; +import net.minestom.server.registry.RegistryKey; +import net.minestom.server.utils.validate.Check; +import net.minestom.server.world.biome.Biome; +import org.jetbrains.annotations.ApiStatus; + +import java.util.AbstractList; +import java.util.Arrays; +import java.util.List; +import java.util.Objects; + +/** + * The {@link LazySectionBlockStorage} class stores the blocks of a chunk in Minestom {@link Section} + * objects again, but allocates one only for a section that holds something: every section which is + * nothing but air points at one shared instance which no chunk owns and none writes to. + *

+ * This is the layout the whole design was built for, and the reason it can exist at all is that + * stage 1 moved the storage out of the chunk. The pattern fits nowhere else. {@code Section} is a + * {@code record} and therefore final, and {@code Palette} is declared + * {@code public sealed interface Palette permits PaletteImpl}, so neither a lazy section nor a lazy + * palette can be handed to Minestom — the sharing has to live one level above both, which is exactly + * where {@link BlockStorage} sits. + *

+ *

+ * What it is worth was counted rather than assumed. A generated overworld holds {@code 62,24 %} of + * the sections of its finished chunks as pure air, over four hundred and forty one chunks around one + * spawn, and at that share the layout saves {@code 2 911} bytes per chunk. Constructing a chunk this + * way allocates {@code 2 104} against {@code 7 096} bytes. Both figures come from + * {@code EmptySectionCensusTest} and {@code LazySectionBenchmark} in {@code falco-benchmarks} and + * carry the conditions stated there; neither is a projection. + *

+ * + *

Why a first write allocates instead of cloning the shared section

+ *

+ * The obvious copy on write step is {@code EMPTY.clone()} and it is the wrong one. + * {@code Section#clone} creates two fresh light carriers and then calls + * {@code skyLight.set(this.skyLight.array())} on them. For the shared section {@code array()} answers + * with {@code LightCompute.UNSET_CONTENT}, a zero length array, and {@code SkyLight#set} turns that + * into {@code LightCompute.EMPTY_CONTENT} — the process wide, mutable {@code byte[2048]} — while + * also setting {@code isValidBorders} and raising {@code needsSend}. A section materialised that way + * would announce that it has light to send before anything ever lit it, and would hold its + * {@code content} field pointing at an array shared with every other section built the same way. + * {@code new Section()} produces the same blocks, leaves the light unset and allocates less, which is + * what {@code LazySectionBenchmark#firstWriteLazy} measured at {@code 2 720 B/op}. + *

+ * + *

What is shared, and the one rule that keeps it safe

+ *

+ * {@link #EMPTY} is never written to by this class. Every write path replaces the slot first, and the + * two accessors that can hand the shared section to a caller — {@link #view(int)} and + * {@link #views()} — document in {@link BlockStorage} that their result is read only. The accessors + * Minestom itself reaches, {@link #section(int)} and {@link #sections()}, materialise instead, because + * a chunk loader or the generator of an {@code InstanceContainer} receives a {@code Section} through + * them and writes into its palettes directly. That is the honest price of this layout and it is + * stated rather than hidden: any caller of {@code Chunk#getSections()} makes this storage as + * expensive as the eager one. + *

+ *

+ * A write of the state the shared section already holds everywhere is skipped rather than + * materialised. That is not an optimisation of a rare case: a loader or a generator which walks a + * whole chunk and writes air into the parts that are air would otherwise materialise every section it + * touched and this class would be strictly worse than the eager one. The check is on the state id and + * not on {@code Block#isAir()}, because cave air and void air are air by that predicate and are + * different states which have to be stored. + *

+ *

+ * Implementations of {@link BlockStorage} are not thread-safe and this one is no exception. The + * caller holds the write lock of the chunk, which is what makes the read of a slot, the decision to + * materialise and the store of the new section one step rather than three. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ApiStatus.Experimental +public final class LazySectionBlockStorage implements BlockStorage { + + /** + * The section every empty slot of every chunk of this process points at. + *

+ * It is never written to. Every write path of this class replaces the slot before it writes, and + * the two read-only accessors document that a caller must not write through what they return. A + * write that reached this object would not corrupt one chunk, it would corrupt every chunk whose + * slot at that height happens to be empty. + *

+ */ + static final Section EMPTY = new Section(); + + /** + * The state id a write has to carry to be worth materialising a shared section for. + *

+ * Read from the registry rather than written down as {@code 0}, so that a Minecraft version which + * renumbered the states cannot silently turn this guard into one that drops real blocks. + *

+ */ + private static final int AIR_STATE = Block.AIR.stateId(); + + /** + * The edge length of the biome grid of a section. + *

+ * Named here for the same reason {@code SectionBlockStorage} names it: {@code Section} has no + * constant for it, and a wrong biome divisor is silent rather than loud. + *

+ */ + private static final int BIOME_SIZE = 4; + + private static final DynamicRegistry BIOME_REGISTRY = MinecraftServer.getBiomeRegistry(); + + private final int minSection; + private final Section[] sections; + + /** + * The list {@link #views()} answers with. + *

+ * It reads through to {@link #sections} rather than copying it, which is what lets a caller take + * it once and still see a section that was materialised afterwards. It is also why {@link #views()} + * allocates nothing: the chunk packet builder walks this list on every send, and a list built per + * send would be a cost this class was written to remove rather than to add. + *

+ */ + private final List
view = new AbstractList<>() { + + @Override + public Section get(int index) { + return LazySectionBlockStorage.this.sections[index]; + } + + @Override + public int size() { + return LazySectionBlockStorage.this.sections.length; + } + }; + + /** + * Creates a storage in which every section is shared. + * + * @param minSection the index of the bottom section of the chunk + * @param sectionCount the amount of sections the chunk spans + */ + public LazySectionBlockStorage(int minSection, int sectionCount) { + this.minSection = minSection; + this.sections = new Section[sectionCount]; + Arrays.fill(this.sections, EMPTY); + } + + /** + * Creates a storage which takes over the given sections. + *

+ * A section which is identical to the shared one is not detected here and is taken over as it + * stands. Deciding otherwise would mean walking four thousand and ninety six positions per + * section to find out, which is more than the slot is worth; a caller which knows that a section + * is empty passes {@link #EMPTY} for it. + *

+ * + * @param minSection the index of the bottom section of the chunk + * @param sections the sections, from the bottom one upwards + */ + public LazySectionBlockStorage(int minSection, List
sections) { + this.minSection = minSection; + this.sections = sections.toArray(new Section[0]); + } + + @Override + public Block getBlock(int x, int y, int z, Block.Getter.Condition condition) { + final Section section = this.sections[CoordConversion.globalToChunk(y) - this.minSection]; + + // US-2.07: a shared section is air everywhere, so the palette is not reached at all. The + // palette of the shared section would answer the same; this is a shortcut, not a special case. + if (section == EMPTY) { + return Block.AIR; + } + final int stateId = section.blockPalette() + .get(x, CoordConversion.globalToSectionRelative(y), z); + + return Objects.requireNonNullElse(Block.fromStateId(stateId), Block.AIR); + } + + @Override + public void setBlock(int x, int y, int z, Block block) { + final int index = CoordConversion.globalToChunk(y) - this.minSection; + final int stateId = block.stateId(); + + if (stateId == AIR_STATE && this.sections[index] == EMPTY) { + return; + } + materialise(index).blockPalette() + .set(x, CoordConversion.globalToSectionRelative(y), z, stateId); + } + + @Override + public RegistryKey getBiome(int x, int y, int z) { + final Section section = this.sections[CoordConversion.globalToChunk(y) - this.minSection]; + final int id = section.biomePalette() + .get(x / BIOME_SIZE, + CoordConversion.globalToSectionRelative(y) / BIOME_SIZE, + z / BIOME_SIZE); + + final RegistryKey biome = BIOME_REGISTRY.getKey(id); + + Check.notNull(biome, "Biome with id {0} is not registered", id); + return biome; + } + + @Override + public void setBiome(int x, int y, int z, RegistryKey biome) { + final int id = BIOME_REGISTRY.getId(biome); + + if (id == -1) throw new IllegalStateException("Biome has not been registered: " + biome.key()); + + final int index = CoordConversion.globalToChunk(y) - this.minSection; + + // Unlike a block write, a biome write is not skipped when it matches what the shared section + // holds. The zero of a biome palette is a registry id and not a sentinel, so the id which + // happens to be zero belongs to a real biome that a caller may legitimately want stored, and + // it is not this class's business to decide that writing it is a no-op. + materialise(index).biomePalette() + .set(x / BIOME_SIZE, + CoordConversion.globalToSectionRelative(y) / BIOME_SIZE, + z / BIOME_SIZE, id); + } + + @Override + public List
sections() { + for (int index = 0; index < this.sections.length; index++) { + materialise(index); + } + return this.view; + } + + @Override + public Section section(int section) { + return materialise(section); + } + + @Override + public Section view(int section) { + return this.sections[section]; + } + + @Override + public List
views() { + return this.view; + } + + @Override + public boolean shared(int section) { + return this.sections[section] == EMPTY; + } + + @Override + public int materialisedSections() { + int owned = 0; + + for (Section section : this.sections) { + if (section != EMPTY) owned++; + } + return owned; + } + + @Override + public int sectionCount() { + return this.sections.length; + } + + @Override + public BlockStorage copy() { + final Section[] copied = new Section[this.sections.length]; + + for (int index = 0; index < copied.length; index++) { + final Section section = this.sections[index]; + copied[index] = section == EMPTY ? EMPTY : section.clone(); + } + return new LazySectionBlockStorage(this.minSection, copied); + } + + @Override + public void clear() { + for (int index = 0; index < this.sections.length; index++) { + final Section section = this.sections[index]; + + if (section == EMPTY) continue; + // Emptied as well as released. A caller which took the section through the boundary + // before the reset holds a reference this class cannot reach, and DynamicChunk#reset + // leaves such a caller with an emptied section rather than with a stale one. + section.clear(); + this.sections[index] = EMPTY; + } + } + + /** + * Gives a slot a section of its own, if it does not have one yet. + * + * @param index the index of the section, counted from the bottom one + * @return the section the slot holds afterwards, which this storage owns + */ + private Section materialise(int index) { + Section section = this.sections[index]; + + if (section == EMPTY) { + section = new Section(); + this.sections[index] = section; + } + return section; + } + + /** + * Creates a storage over an array this class takes ownership of. + * + * @param minSection the index of the bottom section of the chunk + * @param sections the sections, from the bottom one upwards + */ + private LazySectionBlockStorage(int minSection, Section[] sections) { + this.minSection = minSection; + this.sections = sections; + } +} +``` + +**Two things to verify against the pinned sources before running anything.** `Block.CAVE_AIR` has to exist and its state id has to differ from `Block.AIR`; and `Block.AIR.stateId()` has to be resolvable in a static initialiser without `MinecraftServer.init()` having run, which is the same assumption `SectionBlockStorage` already makes with `MinecraftServer.getBiomeRegistry()`. + +```bash +S=/tmp/claude-1000/-mnt-projects-oss-onelitefeather-Falco/34edb948-9dfe-4540-9666-9e29f0d44d7b/scratchpad/minestom-src +grep -n "CAVE_AIR" "$S/net/minestom/server/instance/block/Block.java" | head -3 +``` + +If the static initialiser turns out to need the server, move `AIR_STATE` into a holder class or read it in the constructor — but state which of the two happened, because it is a fact about Minestom and not about this class. + +- [ ] **Step 4: Make the contract test run against both implementations** + +`BlockStorageTest` was written against the interface in stage 1 precisely so this would cost nothing. Replace its private factory with a parameter: + +```java + static java.util.stream.Stream storages() { + return java.util.stream.Stream.of( + org.junit.jupiter.params.provider.Arguments.of("eager", + (java.util.function.Supplier) () -> new SectionBlockStorage(MIN_SECTION, SECTIONS)), + org.junit.jupiter.params.provider.Arguments.of("lazy", + (java.util.function.Supplier) () -> new LazySectionBlockStorage(MIN_SECTION, SECTIONS))); + } +``` + +and turn each `@Test` into a `@ParameterizedTest(name = "{0}")` `@MethodSource("storages")` taking `(String name, Supplier factory)`, with `factory.get()` where `storage()` was. Import the parameterised annotations properly rather than fully qualifying them in the final file; the fully qualified form above is only there so the snippet stands on its own. + +Three of the existing cases move out rather than being parameterised, because they are statements about the eager layout and are already asserted for the lazy one in `LazySectionBlockStorageTest`: + +- `testEagerStorageSharesNothing` stays a plain `@Test` on `SectionBlockStorage`. +- `testViewAndSectionAgree` stays a plain `@Test` on `SectionBlockStorage`; `assertSame(section, view)` is false for the lazy storage by construction. +- `testSectionCount`'s `sections().size()` half stays, since calling `sections()` on the lazy storage materialises everything and would make the case assert the opposite of what this stage is about. Its `sectionCount()` half is parameterised. + +- [ ] **Step 5: Run both test classes** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +./gradlew :falco-instance:test --tests "*BlockStorageTest*" --tests "*LazySectionBlockStorageTest*" +``` + +Expected: PASS. Every contract case passes for both implementations, and the flyweight cases pass for the lazy one. A failure of `testColumnOutsideTheChunkIsRejected` under the lazy storage means the shortcut in `getBlock` swallowed a coordinate the eager one rejected — fix the shortcut, not the test: an out-of-range `x` has to reach a palette and be refused there, which it does for every materialised section and for a shared one only through `setBlock`. If the two layouts genuinely cannot agree on that case, that is a finding about the contract and belongs in the stage result, not in a weakened assertion. + +- [ ] **Step 6: Commit** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +git add falco-instance/src/main/java/net/onelitefeather/falco/instance/LazySectionBlockStorage.java \ + falco-instance/src/test/java/net/onelitefeather/falco/instance/LazySectionBlockStorageTest.java \ + falco-instance/src/test/java/net/onelitefeather/falco/instance/BlockStorageTest.java +git commit -m "feat(instance): share one empty section instead of allocating twenty-four" +``` + +--- + +### Task 3: `FalcoChunk` stops materialising its own sections + +**Files:** +- Modify: `falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoChunk.java` +- Test: covered by Tasks 4 and 9, and by the existing `FalcoChunkEquivalenceTest` in both modules + +**Interfaces:** +- Consumes: `LazySectionBlockStorage`, `BlockStorage#views()`, `#view(int)` from Tasks 1–2. +- Produces: `FalcoChunk` whose default storage is lazy. `FalcoChunk#storage()` is unchanged and is what Task 4 asserts through. + +**Covers:** US-2.01 and US-2.09 at the chunk. + +**Why this is where the stage is won or lost.** `Heightmap#getHighestBlockSection` (`Heightmap.java:134`) walks a chunk from the top downwards calling `chunk.getSection(sectionY).blockPalette()` until it finds a palette with a non-zero count. Those are precisely the empty top sections of an overworld. `FalcoChunk#calculateFullHeightmap` calls it, `setBlock` calls `calculateFullHeightmap` on the first write, and `createChunkPacket` reaches it through `getHeightmaps`. Left as it is, the first block written into a fresh chunk materialises all twenty-four sections and this stage saves nothing. + +- [ ] **Step 1: Read the two methods that force the issue** + +```bash +S=/tmp/claude-1000/-mnt-projects-oss-onelitefeather-Falco/34edb948-9dfe-4540-9666-9e29f0d44d7b/scratchpad/minestom-src +sed -n '60,95p' "$S/net/minestom/server/instance/heightmap/Heightmap.java" +sed -n '128,142p' "$S/net/minestom/server/instance/heightmap/Heightmap.java" +``` + +Note what can and cannot be replaced. `getHighestBlockSection` is `public static` and takes the chunk — it can be replaced by a method of `FalcoChunk` that reads the storage. `refresh(int x, int z, int startY)` cannot: it ends in the `private` `setHeightY`, and `heights` is `private final`, so a subclass override has no way to write the result back. The consequence is stated rather than worked around: an empty section **below** the highest non-empty one is still materialised by a heightmap refresh. In a generated overworld that is no sections at all — the census reports the sections below world height 64 as empty in `0,0 %` of the chunks — but in a world with floating islands it is not, and Task 4 measures which. + +- [ ] **Step 2: Change the four places the chunk reads its own sections** + +Default storage: + +```java + public FalcoChunk(Instance instance, int chunkX, int chunkZ) { + super(instance, chunkX, chunkZ, true); + // Must be built here and not in a field initialiser: the super constructor is what computes + // minSection and maxSection, and the storage is sized from them. + this.storage = new LazySectionBlockStorage(minSection, maxSection - minSection); + } +``` + +The packet builder, in `createChunkPacket`: + +```java + final byte[] data = NetworkBuffer.makeArray(networkBuffer -> { + for (Section section : this.storage.views()) { + final short blockCount = (short) section.blockPalette().count(); + final short liquidCount = (short) (blockCount > 0 ? 1 : 0); //TODO(26.1) proper fluid count + networkBuffer.write(sectionSerializer, + new ChunkData.Section(blockCount, liquidCount, section.blockPalette(), section.biomePalette())); + } + }); +``` + +The light data builder, in `createLightData`: + +```java + for (Section section : this.storage.views()) { +``` + +The snapshot, in `updateSnapshot`: + +```java + final List
sections = this.storage.views(); + final Section[] clonedSections = new Section[sections.size()]; + for (int i = 0; i < clonedSections.length; i++) { + final Section section = sections.get(i); + // A shared section must not end up inside a snapshot even though it never changes: a + // snapshot is read without any lock and by callers this class does not know, and one that + // wrote into it would write into every empty section of the process. A fresh section is + // the same content and cannot be aliased. + clonedSections[i] = this.storage.shared(i) ? new Section() : section.clone(); + } +``` + +And the highest-section scan, replacing the call to Minestom's static helper: + +```java + /** + * Reports the world height at which a heightmap scan of this chunk may start. + *

+ * The body of {@code Heightmap#getHighestBlockSection} with one substitution: it reaches its + * sections through {@code Chunk#getSection(int)}, which is the boundary that hands a section to + * an arbitrary caller and therefore has to create one. Walking a chunk from the build limit + * downwards through that method materialises exactly the empty top sections this chunk exists not + * to hold, on the first block anybody writes into it. Reading through + * {@link BlockStorage#view(int)} answers the same question and creates nothing. + *

+ *

+ * The arithmetic is copied rather than re-derived, including the descent by one section per step + * and the break on the first palette whose count is not zero, because the two have to agree: a + * heightmap computed from a different starting height than Minestom's is not a faster heightmap, + * it is a different one. + *

+ * + * @return the world Y at which the scan starts + */ + private int highestBlockSection() { + int y = instance.getCachedDimensionType().maxY(); + + for (int index = this.storage.sectionCount() - 1; index >= 0; index--) { + if (this.storage.view(index).blockPalette().count() != 0) break; + y -= CHUNK_SECTION_SIZE; + } + return y; + } + + private void calculateFullHeightmap() { + assertWriteLock(); + final int startY = highestBlockSection(); + this.motionBlocking.refresh(startY); + this.worldSurface.refresh(startY); + this.needsCompleteHeightmapRefresh = false; + } +``` + +`getSections()` and `getSection(int)` stay exactly as they are. They are the boundary of US-2.09 and their new behaviour comes entirely from the storage behind them. + +Raise `@version` to `3.0.0` and add a section to the class Javadoc: + +```java + *

Which of its own sections this chunk is allowed to create

+ *

+ * None, on any path of its own. The packet it sends, the light data it collects, the snapshot it + * takes and the scan that starts a heightmap refresh all read through {@link BlockStorage#views()} + * and {@link BlockStorage#view(int)}, which hand out whatever the storage currently holds and create + * nothing. Only {@link #getSections()} and {@link #getSection(int)} materialise, because those two + * are what Minestom calls when it is about to write into a section — the generator of an + * {@code InstanceContainer}, a chunk loader, the light engine — and a storage cannot tell a reader + * from a writer through them. + *

+ *

+ * The one place where that boundary is crossed against this chunk's will is the heightmap. + * {@code Heightmap#refresh(int, int, int)} reaches its sections through {@code Chunk#getSection(int)} + * and cannot be overridden, because it ends in a {@code private} setter over a {@code private} + * array. A refresh therefore materialises every empty section it walks through below the highest + * non-empty one. In a generated overworld that is none; the height profile of the census puts the + * empty share below world height sixty-four at {@code 0,0 %}. In a world of floating islands it is + * not none, and {@code SectionMaterialisationTest} states the number rather than leaving it to the + * imagination. + *

+``` + +- [ ] **Step 3: Compile and run the equivalence tests of both modules** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +./gradlew :falco-instance:test +./gradlew :falco-benchmarks:test --tests "*FalcoChunkEquivalenceTest*" +``` + +Expected: PASS. `FalcoChunkEquivalenceTest` in `falco-benchmarks` is the strongest net on the branch — eighteen fixtures through `MinestomChunks#assertSameBlocks`, every one of the `16·16·16·sectionCount` positions and both heightmaps of every column, plus a scatter batch, a full heightmap refresh and three copy comparisons. If the lazy layout differs from `DynamicChunk` anywhere, this is what says so, and it names the position. + +- [ ] **Step 4: Run the neighbouring modules** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +./gradlew :falco-light:test :falco-anvil:test +``` + +Expected: PASS. `falco-light` and `falco-anvil` reach chunks through `getSections()` (`ChunkLightService:160` and `:405`, `FalcoAnvilLoader:1161`) and `getSection(int)` (`FalcoAnvilLoader:1053`), which materialise. That is the boundary behaving as designed and it must not fail — a failure here means a materialising accessor was missed somewhere. + +- [ ] **Step 5: Commit** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +git add falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoChunk.java +git commit -m "refactor(instance): read the chunk's own sections without creating them" +``` + +--- + +### Task 4: Count what the boundary actually costs + +**Files:** +- Create: `falco-instance/src/test/java/net/onelitefeather/falco/instance/SectionMaterialisationTest.java` + +**Interfaces:** +- Consumes: `FalcoChunk#storage()`, `BlockStorage#materialisedSections()`. +- Produces: nothing. This is the acceptance test of the stage and the answer to the open question the spec's §8 records as *"Materialisation at the three boundaries may undo the saving for workloads that call `getSection` often. No workload has been measured for how often that happens."* + +**Covers:** the boundary half of US-2.09, and the evidence for US-2.01 and US-2.02 at chunk level. + +- [ ] **Step 1: Write the test** + +```java +package net.onelitefeather.falco.instance; + +import net.minestom.server.MinecraftServer; +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.InstanceContainer; +import net.minestom.server.instance.block.Block; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +import static org.junit.jupiter.api.Assertions.assertEquals; + +@DisplayName("What a caller of a Falco chunk makes it allocate") +class SectionMaterialisationTest { + + private static final int SECTIONS = 24; + + private static InstanceContainer container; + + @BeforeAll + static void server() { + if (MinecraftServer.process() == null) { + MinecraftServer.init(); + } + container = MinecraftServer.getInstanceManager().createInstanceContainer(); + } + + private static FalcoChunk chunk() { + return new FalcoChunk(container, 0, 0); + } + + private static int owned(FalcoChunk chunk) { + return chunk.storage().materialisedSections(); + } + + @Test + @DisplayName("a fresh chunk owns nothing") + void testAFreshChunkOwnsNoSection() { + assertEquals(0, owned(chunk())); + } + + @Test + @DisplayName("reading a whole empty chunk owns nothing") + void testReadingOwnsNothing() { + final FalcoChunk chunk = chunk(); + + chunk.lockReadLock(); + try { + for (int y = -64; y < 320; y++) { + chunk.getBlock(0, y, 0); + } + } finally { + chunk.unlockReadLock(); + } + assertEquals(0, owned(chunk)); + } + + @Test + @DisplayName("one write owns one section, and the heightmap refresh that follows owns none") + void testOneWriteOwnsOneSection() { + final FalcoChunk chunk = chunk(); + + chunk.lockWriteLock(); + try { + chunk.setBlock(0, 64, 0, Block.STONE); + } finally { + chunk.unlockWriteLock(); + } + assertEquals(1, owned(chunk), + "a write refreshes both heightmaps, and the scan that starts them walks the chunk " + + "from the build limit downwards; if it goes through Chunk#getSection this " + + "number is 24 and the whole stage is worth nothing"); + } + + @Test + @DisplayName("sending a chunk owns only what the chunk already held") + void testTheFullDataPacketOwnsNothing() { + final FalcoChunk fresh = chunk(); + + fresh.getFullDataPacket(); + assertEquals(0, owned(fresh), + "a chunk that holds nothing has nothing to serialise, and the cached packet is the " + + "hottest boundary there is"); + + final FalcoChunk written = chunk(); + written.lockWriteLock(); + try { + written.setBlock(0, 64, 0, Block.STONE); + } finally { + written.unlockWriteLock(); + } + written.getFullDataPacket(); + assertEquals(1, owned(written)); + } + + @Test + @DisplayName("asking for one section through the Minestom boundary owns exactly that one") + void testGetSectionOwnsOne() { + final FalcoChunk chunk = chunk(); + + chunk.getSection(4); + + assertEquals(1, owned(chunk)); + } + + @Test + @DisplayName("asking for the section list through the Minestom boundary owns the whole chunk") + void testGetSectionsOwnsEverything() { + final FalcoChunk chunk = chunk(); + + chunk.getSections(); + + assertEquals(SECTIONS, owned(chunk), + "this is the price of the boundary and it is stated rather than hidden: a caller " + + "which reaches into the chunk this way makes the lazy layout cost exactly " + + "what the eager one costs"); + } + + @Test + @DisplayName("a copy owns what the original owned") + void testCopyOwnsWhatWasOwned() { + final FalcoChunk chunk = chunk(); + + chunk.lockWriteLock(); + try { + chunk.setBlock(0, 64, 0, Block.STONE); + } finally { + chunk.unlockWriteLock(); + } + chunk.lockReadLock(); + final Chunk copy; + try { + copy = chunk.copy(container, 1, 1); + } finally { + chunk.unlockReadLock(); + } + assertEquals(1, ((FalcoChunk) copy).storage().materialisedSections()); + } + + @Test + @DisplayName("a heightmap refresh over a gap owns the empty sections under the terrain") + void testAGapUnderTheTerrainIsTheKnownLeak() { + final FalcoChunk chunk = chunk(); + + chunk.lockWriteLock(); + try { + chunk.setBlock(0, -64, 0, Block.STONE); + chunk.setBlock(0, 200, 0, Block.STONE); + } finally { + chunk.unlockWriteLock(); + } + chunk.getFullDataPacket(); + + final int owned = owned(chunk); + + assertEquals(SECTIONS - 7, owned, + "Heightmap#refresh(int,int,int) reaches its sections through Chunk#getSection and " + + "cannot be overridden, so every empty section between the floor block and " + + "the one at y=200 is materialised by the column scan. The seven that stay " + + "shared are the ones above y=207. This number is the known cost of the " + + "heightmap and it is asserted so that it cannot grow unnoticed."); + } +} +``` + +- [ ] **Step 2: Run it and let the last case tell the truth** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +./gradlew :falco-instance:test --tests "*SectionMaterialisationTest*" +``` + +Expected: the first seven PASS. `testAGapUnderTheTerrainIsTheKnownLeak` is written with a number derived from the source and will very likely be wrong on the first run — the descent of `Heightmap#refresh(int,int,int)` skips whole sections through `currentY = (sectionY << 4) - 1` and stops at the first matching block per column, so the count depends on the fixture in a way that is easier to read off than to derive. **Correct the number to what the run reports, and only after reading why it is that number.** Write the reason into the message. A number changed until the test is green without an explanation is a plan failure and is worse than no assertion. + +If the reported number is `SECTIONS`, the scan is still going through `Chunk#getSection` somewhere — go back to Task 3 Step 2. + +- [ ] **Step 3: Commit** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +git add falco-instance/src/test/java/net/onelitefeather/falco/instance/SectionMaterialisationTest.java +git commit -m "test(instance): state what every boundary caller makes a lazy chunk allocate" +``` + +--- + +### Task 5: Price `optimize()` before booking it as a gain + +**Files:** +- Create: `falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/GeneratorCommitBenchmark.java` + +**Interfaces:** +- Consumes: `MinestomChunks#ensureServer`, `#newFalcoInstance`, `#newChunk`, `#fill`, `#release`, `BenchmarkConstants#OVERWORLD_SECTIONS`, `#SEED`. +- Produces: nothing but numbers. + +**Covers:** the open risk the spec's §8 records as *"`optimize()` after generation costs time that has not been measured against the generation itself."* + +**Why a new class rather than an arm on an existing one.** `SectionAllocationBenchmark` measures what a chunk costs at construction, `LazySectionBenchmark` measures the flyweight, `ChunkComparisonBenchmark` compares two chunk types on the block accessor path. None of them measures the commit step of a generation, and adding an arm to any of them would mix two subjects in one class whose Javadoc argues for exactly one. The byte side of the question is already answered and must not be re-measured: S9 says a chunk whose sections all went direct holds `203 840` bytes against `84 800` for the same content packed indirectly, from `ChunkFootprintTest` and `PaletteFootprintTest`. What is missing is the time, and only the time. + +- [ ] **Step 1: Write the benchmark** + +```java +package net.onelitefeather.falco.benchmark.instance; + +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.Section; +import net.minestom.server.instance.palette.Palette; +import net.onelitefeather.falco.benchmark.support.BenchmarkConstants; +import net.onelitefeather.falco.benchmark.support.MinestomChunks; +import net.onelitefeather.falco.instance.FalcoInstance; +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.TearDown; +import org.openjdk.jmh.annotations.Warmup; + +import java.util.ArrayList; +import java.util.List; +import java.util.concurrent.TimeUnit; + +/** + * The {@link GeneratorCommitBenchmark} class measures what it costs to call + * {@code Palette#optimize(Optimization.SIZE)} on the palettes of a chunk a generator has just + * filled, and states that cost next to the copy it follows rather than on its own. + *

+ * The byte side of this question is already answered and is not measured again here. A chunk whose + * sections all ended up in direct mode retains {@code 203 840} bytes against {@code 84 800} for the + * same content stored indirectly, a factor of {@code 2,4}, and {@code Palette#optimize} has no caller + * anywhere in the main source tree of Minestom. What nothing in this repository states is the price + * in time. A saving of more than half the memory of a generated chunk is worth a great deal of time, + * but "a great deal" is not a measurement, and this stage refuses to book a gain whose cost is + * unknown. + *

+ * + *

The three arms and why the middle one exists

+ *

+ * {@link #commitPlain()} copies the staged palettes into the sections of a chunk, which is what + * {@code FalcoInstance#applyGenerator} does today. {@link #commitOptimized()} does the same and then + * optimises each palette it wrote. The difference between the two is the whole answer, and it is a + * difference rather than an absolute on purpose: a number for {@code optimize} alone would be + * compared against nothing, while the commit is the step it was added to. + *

+ *

+ * {@link #optimizeAlreadyPacked()} is the control. It optimises palettes which are already at their + * minimum width, which is the case a server pays on every chunk whose generator did not produce a + * wide palette in the first place. {@code PaletteImpl#optimize} still walks all four thousand and + * ninety six entries through {@code getAll} to collect the unique values before it can decide that + * there is nothing to do, so this arm is not free and its distance from zero is what a generator pays + * for chunks the optimisation cannot help. + *

+ * + *

Why the state count is the axis

+ *

+ * {@code PaletteImpl#optimize} branches on the number of distinct values it finds: one value collapses + * to the single value mode through {@code fill}, and anything else goes to {@code downsizeWithPalette} + * under {@code Optimization.SIZE}. The cost of the collection walk is the same in both cases and the + * cost of the rewrite is not, so a single state count would answer one of the two questions and hide + * the other. The axis is the one every other chunk benchmark of this module uses, cut down to the + * three points that separate the branches. + *

+ * + *

Running it

+ * 
{@code
+ * ./gradlew :falco-benchmarks:jmhJar
+ * java -jar falco-benchmarks/build/libs/falco-benchmarks-*-jmh.jar \
+ *     "GeneratorCommitBenchmark" -p distinctStates=1,64,1024 -f 3 -wi 5 -i 5 -prof gc
+ * }
+ *

+ * {@code -prof gc} is not optional. {@code downsizeWithPalette} allocates a new backing array and the + * allocation is part of what the optimisation costs, so a run without the profiler reports half the + * price. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@State(Scope.Thread) +@BenchmarkMode(Mode.AverageTime) +@OutputTimeUnit(TimeUnit.MICROSECONDS) +@Fork(value = 1, jvmArgsAppend = {"-Xms2g", "-Xmx2g"}) +@Warmup(iterations = 5, time = 1) +@Measurement(iterations = 5, time = 1) +public class GeneratorCommitBenchmark { + + /** + * The amount of distinct block states the staged palettes are filled from. + */ + @Param({"1", "64", "1024"}) + public int distinctStates; + + /** + * The instance the fixture chunks are built in. + */ + private FalcoInstance instance; + + /** + * The palettes a generator produced, which every arm copies from and never writes to. + */ + private List staged; + + /** + * The same palettes already reduced to their minimum width, for the control arm. + */ + private List packed; + + /** + * The sections the arms commit into, rebuilt per invocation is too slow, so they are reused and + * overwritten; a commit is a full overwrite of every entry, so nothing carries over. + */ + private Section[] target; + + @Setup(Level.Trial) + public void setUp() { + MinestomChunks.ensureServer(); + this.instance = MinestomChunks.newFalcoInstance(); + + final Chunk source = MinestomChunks.newChunk(this.instance, 0, 0); + MinestomChunks.fill(source, this.distinctStates, MinestomChunks.FillShape.RANDOM_RUNS, + BenchmarkConstants.SEED); + + final List
sections = source.getSections(); + + if (sections.size() != BenchmarkConstants.OVERWORLD_SECTIONS) { + throw new IllegalStateException("The fixture chunk holds " + sections.size() + + " sections but the benchmark is written for " + + BenchmarkConstants.OVERWORLD_SECTIONS); + } + this.staged = new ArrayList<>(sections.size()); + this.packed = new ArrayList<>(sections.size()); + this.target = new Section[sections.size()]; + + for (int index = 0; index < sections.size(); index++) { + final Palette blocks = sections.get(index).blockPalette(); + + this.staged.add(blocks.clone()); + final Palette alreadyPacked = blocks.clone(); + alreadyPacked.optimize(Palette.Optimization.SIZE); + this.packed.add(alreadyPacked); + this.target[index] = new Section(); + } + verifyTheFixtureIsWide(); + } + + @TearDown(Level.Trial) + public void tearDown() { + MinestomChunks.release(this.instance); + this.instance = null; + } + + /** + * Measures the commit as {@code FalcoInstance#applyGenerator} performs it today. + * + * @return the sections that were written, so that nothing can be eliminated + */ + @Benchmark + public Section[] commitPlain() { + for (int index = 0; index < this.target.length; index++) { + this.target[index].blockPalette().copyFrom(this.staged.get(index)); + } + return this.target; + } + + /** + * Measures the same commit with the optimisation this stage adds after it. + * + * @return the sections that were written, so that nothing can be eliminated + */ + @Benchmark + public Section[] commitOptimized() { + for (int index = 0; index < this.target.length; index++) { + final Palette palette = this.target[index].blockPalette(); + palette.copyFrom(this.staged.get(index)); + palette.optimize(Palette.Optimization.SIZE); + } + return this.target; + } + + /** + * Measures the optimisation of palettes that are already at their minimum width. + * + * @return the sections that were written, so that nothing can be eliminated + */ + @Benchmark + public Section[] optimizeAlreadyPacked() { + for (int index = 0; index < this.target.length; index++) { + final Palette palette = this.target[index].blockPalette(); + palette.copyFrom(this.packed.get(index)); + palette.optimize(Palette.Optimization.SIZE); + } + return this.target; + } + + /** + * Refuses a fixture in which the optimisation would have nothing to do. + * + * @throws IllegalStateException if no staged palette is wider than its packed form, which would + * make every number of this run a measurement of a no-op + */ + private void verifyTheFixtureIsWide() { + if (this.distinctStates == 1) { + return; + } + for (int index = 0; index < this.staged.size(); index++) { + if (this.staged.get(index).bitsPerEntry() > this.packed.get(index).bitsPerEntry()) { + return; + } + } + throw new IllegalStateException("Not one of the " + this.staged.size() + " staged palettes is " + + "wider than its optimised form at " + this.distinctStates + " distinct states, so " + + "this trial would report the cost of an optimisation that changes nothing"); + } +} +``` + +- [ ] **Step 2: Run it in the scouting configuration and then in the citable one** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +./gradlew :falco-benchmarks:jmh -Pjmh.quick -Pjmh.include="GeneratorCommitBenchmark" +``` + +Then, for a figure that may be quoted: + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +./gradlew :falco-benchmarks:jmhJar +java -jar falco-benchmarks/build/libs/falco-benchmarks-*-jmh.jar \ + "GeneratorCommitBenchmark" -p distinctStates=1,64,1024 -f 3 -wi 5 -i 5 -prof gc +``` + +Record the three numbers per state count and the ratio `commitOptimized / commitPlain` for the plan's result section. State the machine and its load, as the stage 1 result does. + +- [ ] **Step 3: Decide, in writing, before Task 6 changes anything** + +Append a short block to this file under `## What optimize() costs`, stating the measured ratio and the conditions. If the optimisation turns out to cost more than the generation it follows, Task 6 still adds it but behind a documented decision that says so — the requirement in the spec is US-2.03, a Must, and a Must that is expensive is a Must with a stated price, not a Must that is dropped. + +- [ ] **Step 4: Commit** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +git add falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/GeneratorCommitBenchmark.java \ + docs/superpowers/plans/2026-08-02-falco-lazy-sections.md +git commit -m "test(benchmarks): price the palette optimisation against the commit it follows" +``` + +--- + +### Task 6: The generator commits what it filled, and optimises it + +**Files:** +- Modify: `falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoInstance.java` +- Test: `falco-instance/src/test/java/net/onelitefeather/falco/instance/SectionMaterialisationTest.java` (extended) + +**Interfaces:** +- Consumes: `BlockStorage#view(int)`, `#shared(int)`, `#section(int)`, `#sectionCount()`; `SectionBlockStorage(int, List
)`; `FalcoChunk#storage()`. +- Produces: nothing new in the public API. `FalcoInstance#applyGenerator` and `#applyFork` change behaviour only. + +**Covers:** US-2.03. + +**The problem.** `FalcoInstance#applyGenerator:923` opens with `chunk.getSections()`, which under the lazy storage materialises all twenty-four sections before the generator has written a single block — so a generated chunk would cost exactly what it costs today and S7's `62,24 %` would buy nothing on the path that matters most. `applyFork:1047` reaches `chunk.getSectionAt(sectionStartY)` for every fork section, including ones that carry nothing. + +- [ ] **Step 1: Write the failing test** + +Append to `SectionMaterialisationTest`: + +```java + @Test + @DisplayName("a generator owns only the sections it filled, and leaves the palettes packed") + void testAGeneratorOwnsOnlyWhatItFilled() { + final FalcoInstance instance = new FalcoInstance(MinecraftServer.getDimensionTypeRegistry() + .getKey(net.minestom.server.world.DimensionType.OVERWORLD)); + + instance.setChunkSupplier(FalcoChunk::new); + instance.setGenerator(unit -> unit.modifier() + .fillHeight(-64, 0, Block.STONE)); + + final FalcoChunk chunk = (FalcoChunk) instance.loadChunk(0, 0).join(); + + assertEquals(4, chunk.storage().materialisedSections(), + "stone from y=-64 to y=0 fills exactly four sections; the other twenty hold nothing " + + "and must stay shared"); + + for (int index = 0; index < 4; index++) { + assertEquals(0, chunk.storage().view(index).blockPalette().bitsPerEntry(), + "a section holding one state has to end in the single value mode after " + + "Palette#optimize, not at fifteen bits per entry"); + } + MinecraftServer.getInstanceManager().unregisterInstance(instance); + } +``` + +Construct the `FalcoInstance` the way the existing `FalcoInstanceGeneratorTest` in the same package does rather than the way above if that test uses a different constructor; read it first and follow it, because the instance API is not the subject here. + +- [ ] **Step 2: Run it to verify it fails** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +./gradlew :falco-instance:test --tests "*SectionMaterialisationTest*" +``` + +Expected: FAIL with `24` against the expected `4`, from the `getSections()` at `FalcoInstance:923`. + +- [ ] **Step 3: Rewrite the commit** + +Replace the body of `applyGenerator`: + +```java + private void applyGenerator(Chunk chunk, Generator generator) { + final BlockStorage storage = storageOf(chunk); + final int sectionCount = storage.sectionCount(); + final GeneratorImpl.GenSection[] staged = new GeneratorImpl.GenSection[sectionCount]; + Arrays.setAll(staged, index -> { + final Section view = storage.view(index); + return new GeneratorImpl.GenSection(view.blockPalette().clone(), view.biomePalette().clone()); + }); + final GeneratorImpl.UnitImpl unit = GeneratorImpl.chunk(this.registries.biome(), staged, + chunk.getChunkX(), chunk.getMinSection(), chunk.getChunkZ()); + + generator.generate(unit); + + chunk.lockWriteLock(); + try { + for (int index = 0; index < sectionCount; index++) { + commitSection(chunk, storage, index, staged[index]); + } + chunk.invalidate(); + } finally { + chunk.unlockWriteLock(); + } + + applyForks(chunk, unit); + applyPendingForks(chunk); + refreshLastBlockChangeTime(); + } + + /** + * Writes one generated section back into the chunk, or leaves the chunk alone if it produced + * nothing. + *

+ * The skip is what makes a lazy layout survive its own generator. A generator normally fills the + * lower third of a chunk and leaves everything above the terrain untouched — the census of a real + * overworld puts that untouched share at {@code 62,24 %} of the sections of a finished chunk — and + * committing an empty palette into an empty section would create twenty-four sections to write + * nothing into twenty of them. The condition is the one {@code InstanceContainer} already applies + * to fork sections at {@code InstanceContainer.java:434}, extended by the biomes and by the special + * blocks, since either of those can be the only thing a generator produced for a section. + *

+ *

+ * A section that is still shared and received nothing needs no write at all, and that is exactly + * what the condition tests. A section the chunk already owns is committed unconditionally: it + * holds content from a loader or an earlier write, and an empty generated palette is a statement + * about what the generator produced and not about what the chunk should end up holding. + *

+ *

+ * The optimisation afterwards is US-2.03. A generator writes through {@code GenSection} palettes + * which grow to fifteen bits per entry and never shrink again, because nothing in the main source + * tree of Minestom ever calls {@code Palette#optimize} — a generated chunk retains + * {@code 203 840} bytes where the same content packed to its minimum width retains {@code 84 800}. + * What that costs in time is measured by {@code GeneratorCommitBenchmark} and stated in the plan + * of this stage; it is not assumed to be free. + *

+ * + * @param chunk the chunk which receives the section + * @param storage the storage of the chunk + * @param index the index of the section, counted from the bottom one + * @param generated the section the generator produced + */ + private void commitSection(Chunk chunk, BlockStorage storage, int index, + GeneratorImpl.GenSection generated) { + final boolean producedNothing = generated.blocks().count() == 0 + && generated.biomes().count() == 0 + && generated.specials().isEmpty(); + + if (producedNothing && storage.shared(index)) { + return; + } + final Section section = storage.section(index); + + section.blockPalette().copyFrom(generated.blocks()); + section.biomePalette().copyFrom(generated.biomes()); + section.blockPalette().optimize(Palette.Optimization.SIZE); + section.biomePalette().optimize(Palette.Optimization.SIZE); + writeSpecialBlocks(chunk, generated.specials(), + (chunk.getMinSection() + index) * Chunk.CHUNK_SECTION_SIZE); + } + + /** + * Hands out the storage of a chunk, whatever kind of chunk it is. + *

+ * A chunk supplier is a setting of the instance and a caller is free to install one which does not + * produce a {@link FalcoChunk}. Rather than carrying two generation paths, a foreign chunk is + * wrapped in a {@link SectionBlockStorage} over its own live sections: that storage shares nothing + * and materialises nothing, so every decision below it collapses into the behaviour Minestom has, + * and the writes go straight into the sections of the chunk because the list holds the same + * {@code Section} references. + *

+ * + * @param chunk the chunk to reach the sections of + * @return the storage of the chunk + */ + private static BlockStorage storageOf(Chunk chunk) { + if (chunk instanceof FalcoChunk falcoChunk) { + return falcoChunk.storage(); + } + return new SectionBlockStorage(chunk.getMinSection(), chunk.getSections()); + } +``` + +And guard `applyFork` against a fork section that carries nothing, which is the same guard `InstanceContainer` has at `:434`: + +```java + private void applyFork(Chunk chunk, GeneratorImpl.SectionModifierImpl modifier) { + if (modifier.genSection().blocks().count() == 0 && modifier.genSection().specials().isEmpty()) { + // A fork which produced nothing for this section must not be the reason the section + // exists. Minestom applies the same test at InstanceContainer.java:434 for the same reason. + return; + } + final int sectionStartY = modifier.start().blockY(); + chunk.lockWriteLock(); + try { + final Palette blocks = chunk.getSectionAt(sectionStartY).blockPalette(); + // A forked section marks an untouched position with a zero, so every block it does carry + // was stored with its state raised by one and has to be lowered again here. + modifier.genSection().blocks().getAllPresent((x, y, z, value) -> blocks.set(x, y, z, value - 1)); + writeSpecialBlocks(chunk, modifier.genSection().specials(), sectionStartY); + chunk.invalidate(); + } finally { + chunk.unlockWriteLock(); + } + } +``` + +New imports for `FalcoInstance`: `net.minestom.server.instance.palette.Palette` if it is not already there. Raise the `@version` of the class and add a paragraph to the Javadoc of `applyGenerator` saying that the palettes the generator wrote into are copies sized from the *views* of the chunk, so that staging a generation no longer creates the sections the generator may decide not to fill. + +- [ ] **Step 4: Run the tests** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +./gradlew :falco-instance:test +./gradlew :falco-anvil:test :falco-light:test +``` + +Expected: PASS, including the new generator case at `4` materialised sections and `bitsPerEntry() == 0`. `FalcoInstanceGeneratorTest` is the regression net for the commit and must stay green without being touched; if it fails, the commit changed what a generator produces and that is a defect, not a test to update. + +- [ ] **Step 5: Commit** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +git add falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoInstance.java \ + falco-instance/src/test/java/net/onelitefeather/falco/instance/SectionMaterialisationTest.java +git commit -m "feat(instance): commit only the sections a generator filled, and pack their palettes" +``` + +--- + +### Task 7: Heightmaps on demand + +**Files:** +- Modify: `falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoChunk.java` +- Test: `falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoChunkTest.java` (extended) + +**Interfaces:** +- Consumes: nothing new. +- Produces: `FalcoChunk#motionBlockingHeightmap()` and `#worldSurfaceHeightmap()` create their heightmap on first call. `FalcoChunk#hasHeightmaps()` is added for the tests and for Task 9, because a property that cannot be observed cannot be asserted. + +**Covers:** US-2.04. + +**What this is worth and under which condition.** Both heightmaps together are `1 120` bytes and `16,4 %` of a fresh chunk — the second largest post after the sections, and one the research that preceded this design never listed. The condition has to be stated with the saving: `FalcoChunk#setBlock` refreshes both heightmaps on every write and `createChunkPacket` asks for both on every send, so a chunk that is written to or sent builds them immediately. What is saved is the chunk that is loaded and read and never sent — and, on the generator path, the whole window between construction and the first send. + +- [ ] **Step 1: Write the failing test** + +Append to `FalcoChunkTest`: + +```java + @Test + @DisplayName("builds no heightmap until something asks for one") + void testHeightmapsAreBuiltOnDemand() { + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + + assertFalse(chunk.hasHeightmaps(), "a chunk that was only constructed needs no heightmap"); + + chunk.lockReadLock(); + try { + chunk.getBlock(0, 0, 0); + } finally { + chunk.unlockReadLock(); + } + assertFalse(chunk.hasHeightmaps(), "a block read does not need a heightmap either"); + + assertNotNull(chunk.motionBlockingHeightmap()); + assertTrue(chunk.hasHeightmaps()); + } + + @Test + @DisplayName("hands out the same heightmap on every call") + void testTheHeightmapIsBuiltOnce() { + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + + assertSame(chunk.motionBlockingHeightmap(), chunk.motionBlockingHeightmap()); + assertSame(chunk.worldSurfaceHeightmap(), chunk.worldSurfaceHeightmap()); + assertNotSame(chunk.motionBlockingHeightmap(), chunk.worldSurfaceHeightmap()); + } +``` + +Use the fixture the existing `FalcoChunkTest` already sets up; the `instance` above is whatever that class names it. + +- [ ] **Step 2: Run it to verify it fails** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +./gradlew :falco-instance:test --tests "*FalcoChunkTest*" +``` + +Expected: compilation failure — `hasHeightmaps` does not exist. + +- [ ] **Step 3: Implement** + +Replace the two heightmap fields and their accessors in `FalcoChunk`: + +```java + /** + * The highest block per column which stops movement, built when something first asks for it. + *

+ * Volatile because the creation below is a double-checked lock, and a non-volatile field would + * let a second thread see a partly constructed {@code MotionBlockingHeightmap} — which carries a + * {@code short[256]} of its own that would then be read before it exists. + *

+ */ + private volatile Heightmap motionBlocking; + + /** + * The highest block per column which is not air, built when something first asks for it. + */ + private volatile Heightmap worldSurface; +``` + +```java + /** + * Hands out the heightmap of the highest movement-blocking block per column, building it if this + * chunk does not have one yet. + *

+ * A heightmap is a {@code short[256]} plus its carrier, and both heightmaps together are one sixth + * of everything a fresh chunk retains. Minestom builds them in a field initialiser, so a chunk + * pays for them whether or not anybody ever reads a height. Most chunks do get asked eventually — + * a chunk that is sent to a client hands both of them to the packet, and a chunk that is written + * to refreshes both — but the window between construction and that first question is exactly the + * window a chunk loader and a generator work in, and a chunk that is loaded, read and never sent + * never leaves it. + *

+ *

+ * The creation is a double-checked lock over the monitor of this chunk rather than a plain lazy + * field. The read lock and the write lock of a chunk do not cover this method — a caller may reach + * it without either — and two threads which both created a heightmap would leave one of them + * holding heights that the chunk then throws away. + *

+ * + * @return the motion blocking heightmap + */ + @Override + public Heightmap motionBlockingHeightmap() { + Heightmap heightmap = this.motionBlocking; + + if (heightmap != null) return heightmap; + synchronized (this) { + heightmap = this.motionBlocking; + if (heightmap == null) { + heightmap = new MotionBlockingHeightmap(this); + this.motionBlocking = heightmap; + } + return heightmap; + } + } + + /** + * Hands out the heightmap of the highest non-air block per column, building it if this chunk does + * not have one yet. + * + * @return the world surface heightmap + */ + @Override + public Heightmap worldSurfaceHeightmap() { + Heightmap heightmap = this.worldSurface; + + if (heightmap != null) return heightmap; + synchronized (this) { + heightmap = this.worldSurface; + if (heightmap == null) { + heightmap = new WorldSurfaceHeightmap(this); + this.worldSurface = heightmap; + } + return heightmap; + } + } + + /** + * Reports whether this chunk has built its heightmaps yet. + *

+ * Exposed because a property nothing can observe is a property nothing can assert, and the whole + * value of building them on demand is the claim that a chunk which was only loaded holds none. + *

+ * + * @return whether either heightmap exists + * @since 0.4.0 + */ + public boolean hasHeightmaps() { + return this.motionBlocking != null || this.worldSurface != null; + } +``` + +Then replace every remaining direct use of the two fields inside the class with the accessors — `setBlock`, `calculateFullHeightmap` and `getHeightmaps` all read `this.motionBlocking` and `this.worldSurface` today and must go through `motionBlockingHeightmap()` and `worldSurfaceHeightmap()` instead, or they will dereference null. + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +grep -n "this.motionBlocking\|this.worldSurface" falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoChunk.java +``` + +Every hit outside the two accessors and the two field declarations is a bug. + +- [ ] **Step 4: Run the tests** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +./gradlew :falco-instance:test +./gradlew :falco-benchmarks:test --tests "*FalcoChunkEquivalenceTest*" +``` + +Expected: PASS. The equivalence test compares both heightmaps of every column against `DynamicChunk` and is what says that building them later did not build them differently. + +- [ ] **Step 5: Commit** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +git add falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoChunk.java \ + falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoChunkTest.java +git commit -m "perf(instance): build a heightmap when something asks for one" +``` + +--- + +### Task 8: One block map instead of two + +**Files:** +- Modify: `falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoChunk.java` +- Test: `falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoChunkTest.java` (extended) + +**Interfaces:** +- Consumes: nothing new. +- Produces: `FalcoChunk#tickableMap` is gone. Nothing outside the class reads it; it was `protected`, so the removal is a source-compatible change only for subclasses in this repository, of which there are none. + +**Covers:** US-2.06. + +**The trade, stated before it is made.** `tickableMap` holds a subset of `entries` under identical keys with identical references. Removing it saves one `Int2ObjectOpenHashMap` and its two backing arrays per chunk, and costs a walk over `entries` in `tick` instead of over a smaller map. The walk is guarded by a counter, so a chunk with block entities and no tickable ones still ticks in a single comparison — which is the property the current Javadoc of `tickableMap` argues for and which must not be lost while the map is. + +- [ ] **Step 1: Write the failing test** + +Append to `FalcoChunkTest`: + +```java + @Test + @DisplayName("ticks a tickable handler and stops ticking it when it is replaced") + void testTickReachesOnlyTickableBlocks() { + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + final java.util.concurrent.atomic.AtomicInteger ticks = new java.util.concurrent.atomic.AtomicInteger(); + final BlockHandler tickable = new BlockHandler() { + + @Override + public net.kyori.adventure.key.Key getKey() { + return net.kyori.adventure.key.Key.key("falco", "tickable"); + } + + @Override + public boolean isTickable() { + return true; + } + + @Override + public void tick(Tick tick) { + ticks.incrementAndGet(); + } + }; + + chunk.lockWriteLock(); + try { + chunk.setBlock(0, 0, 0, Block.STONE.withHandler(tickable)); + } finally { + chunk.unlockWriteLock(); + } + chunk.tick(0L); + assertEquals(1, ticks.get()); + + chunk.lockWriteLock(); + try { + chunk.setBlock(0, 0, 0, Block.STONE); + } finally { + chunk.unlockWriteLock(); + } + chunk.tick(0L); + assertEquals(1, ticks.get(), "a block that was replaced must stop being ticked"); + } + + @Test + @DisplayName("carries the tickable blocks of a chunk into its copy") + void testCopyKeepsTicking() { + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + final java.util.concurrent.atomic.AtomicInteger ticks = new java.util.concurrent.atomic.AtomicInteger(); + + chunk.lockWriteLock(); + try { + chunk.setBlock(0, 0, 0, Block.STONE.withHandler(tickingHandler(ticks))); + } finally { + chunk.unlockWriteLock(); + } + chunk.lockReadLock(); + final Chunk copy; + try { + copy = chunk.copy(instance, 1, 1); + } finally { + chunk.unlockReadLock(); + } + copy.tick(0L); + assertEquals(1, ticks.get(), + "DynamicChunk#copy carries only the entries, which stops a copied chunk from ticking; " + + "that omission was corrected before the storage moved and stays corrected"); + } +``` + +Extract the handler into a `tickingHandler(AtomicInteger)` helper of the test class and use it in both cases; the inline form above is written out once so the shape of the handler is on the page. + +- [ ] **Step 2: Run it to verify it passes before the change and after it** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +./gradlew :falco-instance:test --tests "*FalcoChunkTest*" +``` + +Expected: PASS **before** the change. This is a characterisation test rather than a red one: the behaviour it pins already exists and the point of writing it first is that the change must not alter it. Commit it separately, so that the diff of the change shows a green test staying green rather than a test appearing next to it. + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +git add falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoChunkTest.java +git commit -m "test(instance): pin what ticking a chunk does before the second map goes" +``` + +- [ ] **Step 3: Remove the map** + +Delete the `tickableMap` field and add the counter: + +```java + /** + * How many of {@link #entries} carry a handler which asked to be ticked. + *

+ * This is what is left of the second map {@code DynamicChunk} keeps. That map held a subset of + * {@link #entries} under the same keys pointing at the same blocks, so it was a second copy of + * information the chunk already had, at the price of one {@code Int2ObjectOpenHashMap} and its two + * backing arrays per chunk — for every chunk in a world, whether or not it holds a single block + * entity. + *

+ *

+ * What that map bought was the early exit of {@link #tick(long)}: almost every chunk has nothing + * to tick, and a tick which had to walk the entries to find that out would make the cost of + * ticking depend on how many block entities a chunk happens to hold. The counter buys the same + * exit for four bytes. What is genuinely paid is the case that remains — a chunk which holds both + * tickable and non-tickable block entities now walks all of them once per tick instead of only the + * tickable ones. + *

+ */ + private int tickableCount; +``` + +In `setBlock`, replace the two map updates with one map update and a counter correction: + +```java + final int index = CoordConversion.chunkBlockIndex(x, y, z); + // Handler + final BlockHandler handler = block.handler(); + final Block lastCachedBlock; + if (handler != null || block.hasNbt() || block.registry().isBlockEntity()) { + lastCachedBlock = this.entries.put(index, block); + } else { + lastCachedBlock = this.entries.remove(index); + } + // Block tick. A tickable block always carries a handler and is therefore always in the + // entries above, so the counter and the map can never disagree about who is in which. + final BlockHandler previousHandler = lastCachedBlock == null ? null : lastCachedBlock.handler(); + final boolean wasTickable = previousHandler != null && previousHandler.isTickable(); + final boolean isTickable = handler != null && handler.isTickable(); + if (wasTickable != isTickable) { + this.tickableCount += isTickable ? 1 : -1; + } +``` + +In `tick`: + +```java + @Override + public void tick(long time) { + if (this.tickableCount == 0) return; + this.entries.int2ObjectEntrySet().fastForEach(entry -> { + final Block block = entry.getValue(); + final BlockHandler handler = block.handler(); + if (handler == null || !handler.isTickable()) return; + final Point blockPosition = CoordConversion.chunkBlockIndexGetGlobal(entry.getIntKey(), chunkX, chunkZ); + handler.tick(new BlockHandler.Tick(block, instance, blockPosition)); + }); + } +``` + +In `copy`, replace `copy.tickableMap.putAll(this.tickableMap);` with `copy.tickableCount = this.tickableCount;` and keep the paragraph of the Javadoc that explains why a copy has to keep ticking at all. + +In `reset`, add `this.tickableCount = 0;` next to `this.entries.clear();`. + +- [ ] **Step 4: Run the tests** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +./gradlew :falco-instance:test +``` + +Expected: PASS, with the two characterisation cases unchanged. If `testTickReachesOnlyTickableBlocks` fails on the second assertion, the counter was not decremented when the handler was replaced by one without a handler. + +- [ ] **Step 5: Commit** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +git add falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoChunk.java +git commit -m "perf(instance): keep one block map and a counter instead of two maps" +``` + +--- + +### Task 9: Reset the footprint expectation, deliberately + +**Files:** +- Modify: `falco-benchmarks/src/test/java/net/onelitefeather/falco/benchmark/instance/ChunkFootprintTest.java` + +**Interfaces:** +- Consumes: `FalcoChunk` and `LazySectionBlockStorage` as Tasks 2, 3, 7 and 8 left them. +- Produces: nothing. This task changes an assertion and nothing else. + +**Covers:** NFR-003; the measurement half of US-2.05; and the refusal of US-2.08, with its evidence. + +**Why the old assertion has to go, and what must not go with it.** Stage 1 asserted that `FalcoChunk` and `DynamicChunk` retain identical objects and identical bytes in every class except `SectionBlockStorage`, of which the Falco side holds exactly one — with three injected defects used to prove the assertion still bit. Every task of this stage breaks that by construction, because removing objects is the point. What must survive the rewrite is the property the equality had: **a class the Falco chunk retains and the plan did not declare has to fail the test.** A tolerance of the form "at most N bytes" would not have that property and is rejected. The replacement is a declared difference table: every class in it is asserted at an exact count, and every class not in it is still asserted equal on both objects and bytes. + +- [ ] **Step 1: Read what the chunk now holds, before writing what it should hold** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +./gradlew :falco-benchmarks:test --tests "*ChunkFootprintTest*" -i 2>&1 | tee /tmp/claude-1000/-mnt-projects-oss-onelitefeather-Falco/34edb948-9dfe-4540-9666-9e29f0d44d7b/scratchpad/footprint-stage2.txt +``` + +The test fails at this point; the class table it printed before failing is what this step is for. Read the two per-class tables — the fresh chunk and the filled rows — and write down, for every class where the two sides differ, the count on each side. + +- [ ] **Step 2: Derive the table from the source, then compare it with what was printed** + +The expected difference for a **fresh** chunk, derived from the tasks above and not from the measurement: + +| class | `DynamicChunk` | `FalcoChunk` | why | +|---|---|---|---| +| `net.minestom.server.instance.Section` | 24 | 0 | every slot shares `LazySectionBlockStorage.EMPTY`, which is static and therefore not retained by the chunk | +| `...instance.palette.PaletteImpl` | 48 | 0 | two per section, and there are no sections | +| `...instance.light.SkyLight` | 24 | 0 | one per section | +| `...instance.light.BlockLight` | 24 | 0 | one per section | +| `java.util.concurrent.atomic.AtomicBoolean` | 48 | 0 | one per light carrier — US-2.05 for every empty section, achieved by the flyweight rather than by packing | +| `...heightmap.MotionBlockingHeightmap` | 1 | 0 | Task 7 | +| `...heightmap.WorldSurfaceHeightmap` | 1 | 0 | Task 7 | +| `[S` | 2 | 0 | the `short[256]` of each heightmap | +| `it.unimi.dsi.fastutil.ints.Int2ObjectOpenHashMap` | 2 | 1 | Task 8 | +| `[Ljava.lang.Object;` | *n* | *n* − 2 | the two backing arrays of the removed map; read the count off the table | +| `net.onelitefeather.falco.instance.LazySectionBlockStorage` | 0 | 1 | the storage | +| `[Lnet.minestom.server.instance.Section;` | 0 | 1 | the slot array of the storage | +| `net.onelitefeather.falco.instance.LazySectionBlockStorage$1` | 0 | 1 | the `AbstractList` that `views()` answers with | +| `java.util.ImmutableCollections$ListN` | 1 | 0 | Minestom's `List.of(Section[])`; Falco holds the array directly | + +For the **filled** rows the difference is smaller and must be declared separately: `MinestomChunks#fill` writes through `Chunk#setBlock`, so every section is materialised and both heightmaps are built. What remains is the second block map, the storage, the slot array, the view list and the list wrapper. + +**Where the printed table disagrees with this one, the disagreement is the result, not the table.** Do not adjust a row until it is green. Find out which object the chunk holds that this plan did not predict, name it, and write it into the stage result as a finding. + +- [ ] **Step 3: Rewrite the assertion** + +Replace `assertTheSeamIsTheOnlyDifference` with a version that takes the declared table: + +```java + /** + * Fails unless the two chunks differ in exactly the classes this stage declared they differ in. + *

+ * The comparison of stage 1 demanded equality everywhere except one class, and it could, because + * the seam added one object and removed none. Stage 2 removes a hundred and seventy of them, so + * equality is no longer the right shape — but the property it existed for is unchanged and is + * preserved here: a class the Falco chunk retains and this table does not name still fails, on + * both its object count and its bytes. What is asserted per declared class is the count, exactly, + * on both sides; what is asserted over the whole footprint is that the byte difference is the sum + * of the bytes of the declared classes and of nothing else. That is a stronger statement than the + * old equality and not a weaker one, because the old equality never had to add anything up. + *

+ *

+ * A tolerance was considered and rejected. "The Falco chunk retains at most six kibibytes" would + * pass for a chunk that saved the sections and grew a field, which is the exact failure the strict + * comparison of stage 1 was written to catch and the reason three defects were injected into it to + * prove that it did. + *

+ * + * @param minestom the footprint of the Minestom side + * @param minestomChunk the chunk the Minestom side was measured from + * @param falcoSide the footprint of the Falco side + * @param falcoChunk the chunk the Falco side was measured from + * @param declared the expected count per class on the Falco side, for every class the two + * sides may differ in + * @param context what was measured, named in every failure message + */ + private static void assertOnlyTheDeclaredClassesDiffer(Footprint minestom, Chunk minestomChunk, + Footprint falcoSide, Chunk falcoChunk, + Map declared, + String context) { + final String minestomType = minestomChunk.getClass().getName(); + final String falcoType = falcoChunk.getClass().getName(); + + final Set classNames = new TreeSet<>(minestom.perClass().keySet()); + classNames.addAll(falcoSide.perClass().keySet()); + + long declaredBytes = 0; + + for (String className : classNames) { + if (className.startsWith(minestomType) || className.startsWith(falcoType)) { + continue; + } + final Long expected = declared.get(className); + + if (expected == null) { + assertEquals(minestom.objectsOf(className), falcoSide.objectsOf(className), + context + ": FalcoChunk retains " + falcoSide.objectsOf(className) + " objects of " + + className + " against " + minestom.objectsOf(className) + " of DynamicChunk, " + + "and this class is not one the plan of stage 2 declared a difference for"); + assertEquals(minestom.bytesOf(className), falcoSide.bytesOf(className), + context + ": FalcoChunk retains " + falcoSide.bytesOf(className) + " bytes of " + + className + " against " + minestom.bytesOf(className) + " of DynamicChunk, " + + "and this class is not one the plan of stage 2 declared a difference for"); + continue; + } + assertEquals(expected.longValue(), falcoSide.objectsOf(className), + context + ": the plan declares " + expected + " objects of " + className + + " on the Falco side and the chunk holds " + falcoSide.objectsOf(className)); + declaredBytes += falcoSide.bytesOf(className) - minestom.bytesOf(className); + } + assertEquals(declaredBytes, falcoSide.bytes() - minestom.bytes(), + context + ": the two chunks differ by " + (falcoSide.bytes() - minestom.bytes()) + + " bytes while the classes the plan declared account for " + declaredBytes + + ". The remainder belongs to a class this comparison did not look at, which " + + "means a post moved without anybody deciding that it should."); + assertEquals(ClassLayout.parseInstance(minestomChunk).instanceSize(), + ClassLayout.parseInstance(falcoChunk).instanceSize(), + context + ": the two chunk objects themselves must still have the same shallow size"); + } +``` + +Declare the two tables as constants of the class, each entry carrying the count derived in Step 2, and pass the right one from each of the two test methods. Then add the three assertions that carry the *result* of the stage rather than its bookkeeping: + +```java + assertEquals(0, falcoFootprint.objectsOf(SECTION), + "a fresh Falco chunk shares every section and must own none"); + assertEquals(0, falcoFootprint.objectsOf(NEEDS_SEND), + "the 48 AtomicBoolean send flags of a fresh chunk are gone with the sections that " + + "held them; the ones that come back with a materialised section are two per " + + "section and are what US-2.05 does not remove"); + assertTrue(falcoFootprint.bytes() * 4 < minestom.bytes(), + "a fresh Falco chunk retained " + falcoFootprint.bytes() + " bytes against " + + minestom.bytes() + " for a DynamicChunk; the sections are 74,9 % of that " + + "figure and both heightmaps another 16,4 %, so anything above a quarter " + + "means one of the two did not actually go"); +``` + +Finally, add the measurement that refuses US-2.08 with evidence rather than with an opinion: + +```java + /** + * States what the chunk identifier costs and why this stage does not remove it. + *

+ * US-2.08 asks for the {@code UUID} of a chunk to go, on the grounds that {@code grep + * getIdentifier} finds only its declaration in all of Minestom. It cannot go from here. + * {@code Chunk.java:47} declares {@code private final UUID identifier} and {@code Chunk.java:65} + * assigns it {@code UUID.randomUUID()} in the constructor every subclass has to call. A subclass + * cannot remove a field of its superclass, and not extending {@code Chunk} is not available + * either, because {@code Instance} is typed on it throughout. What this test does instead is + * state the price, so that the story is closed by a number rather than by a shrug. + *

+ */ + @Test + @DisplayName("The chunk identifier cannot be removed from a subclass, and this is what it costs") + void theChunkIdentifierIsOutOfReach() { + JolMeasurement.require(); + + final Chunk falcoChunk = MinestomChunks.newChunk(falco, 0, 0); + final Footprint falcoFootprint = measure(falcoChunk, falco); + + assertEquals(1, falcoFootprint.objectsOf("java.util.UUID"), + "every chunk of Minestom allocates one UUID in the constructor of Chunk"); + report(new StringBuilder() + .append(" The chunk identifier costs ") + .append(falcoFootprint.bytesOf("java.util.UUID")) + .append(" bytes per chunk and is unreachable from a subclass (Chunk.java:47, :65).") + .append(System.lineSeparator())); + } +``` + +Raise the class Javadoc of `ChunkFootprintTest` to `@version 2.0.0` and rewrite its `

What the seam costs, and why the delta is not zero

` section into one that describes the declared difference table and names the stage that set it. + +- [ ] **Step 4: Prove the new assertion still bites** + +Inject each of these into `FalcoChunk`, run the test, confirm it fails with a message that names the cause, then revert: + +| injected | has to be caught by | +|---|---| +| `private final Object probe = new Object();` | the undeclared-class branch, `1` object of `java.lang.Object` against `0` | +| `private final BlockStorage probe = new LazySectionBlockStorage(0, 0);` | the declared count, `2` storages against the declared `1` | +| `private final long probe = System.nanoTime();` | the shallow size comparison of the chunk object | +| a `new Section()` in the constructor, stored in a field | the declared count of `Section`, `1` against `0` | + +The fourth is new and is the one this stage needs: it is the shape of the defect where somebody quietly materialises a section to make something else work. + +- [ ] **Step 5: Run it** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +./gradlew :falco-benchmarks:test --tests "*ChunkFootprintTest*" -i +``` + +Expected: PASS, with the tables printed and the fresh-chunk row showing a `DELTA B` that is now large and negative. + +- [ ] **Step 6: Commit** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +git add falco-benchmarks/src/test/java/net/onelitefeather/falco/benchmark/instance/ChunkFootprintTest.java +git commit -m "test(benchmarks): declare what the lazy chunk no longer holds, class by class" +``` + +--- + +### Task 10: Run the measurements and record what stage 2 bought + +**Files:** +- Modify: `docs/superpowers/plans/2026-08-02-falco-lazy-sections.md` + +**Interfaces:** none. This task produces the numbers and the sentence that is allowed to be quoted from them. + +- [ ] **Step 1: The whole test suite** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +./gradlew :falco-instance:test :falco-light:test :falco-anvil:test :falco-benchmarks:test --rerun-tasks +``` + +Expected: no failure, no error. Record the test counts per module against the stage 1 result — 66, 189, 193 and 36 — so that a test that quietly stopped running is visible. + +- [ ] **Step 2: The footprint, which is the citable number of this stage** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +./gradlew :falco-benchmarks:test --tests "*ChunkFootprintTest*" -i +./gradlew :falco-benchmarks:test --tests "*ChunkFootprintTest*" -Pfalco.compactHeaders -i +``` + +Record both, and never quote a number from one next to a number from the other. The row that matters is the fresh chunk: `192` objects and `6 848` bytes for `DynamicChunk`, `193` and `6 872` after stage 1, and whatever this stage leaves. + +- [ ] **Step 3: The flyweight benchmark, which already exists** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +./gradlew :falco-benchmarks:jmhJar +java -jar falco-benchmarks/build/libs/falco-benchmarks-*-jmh.jar \ + "LazySectionBenchmark.(scatteredRead|buildSections).*" \ + -p emptyPercent=0,62,90 -f 3 -wi 5 -i 5 -prof gc +java -jar falco-benchmarks/build/libs/falco-benchmarks-*-jmh.jar \ + "LazySectionBenchmark.(readEmpty|readFull|steadyWrite|firstWrite).*" \ + -p emptyPercent=90 -f 3 -wi 5 -i 5 -prof gc +``` + +The second command answers US-2.07 directly: `readEmptyLazy` against `readEmptyEager` has to be at least as fast, and `readFullLazy` against `readFullEager` has to be indistinguishable. A `readFullLazy` outside the error bars of `readFullEager` means the branch this stage added is being paid on every block read of every non-empty section in the server, and that is a finding which outweighs the memory. + +- [ ] **Step 4: The comparison benchmark, the regression net** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +./gradlew :falco-benchmarks:jmh -Pjmh.quick \ + -Pjmh.include="ChunkComparisonBenchmark" \ + -Pjmh.params="distinctStates=1,64,1024;fillShape=RANDOM_RUNS" +``` + +`falcoGetBlock`, `falcoSetBlock`, `falcoHeightmapRefresh` and `falcoCopyIsolated` against their `minestom*` counterparts. `minestomCopy`/`falcoCopy` are not comparable and are omitted, as the stage 1 result explains. Note that the stage 1 run left `falcoHeightmapRefresh` at 1 024 states unresolved — an error bar twenty-eight times its own mean on a loaded machine — and that this stage changes exactly that path, so it has to be rerun on an idle machine before anything is concluded from it in either direction. + +- [ ] **Step 5: Write the result section** + +Append `## Stage 2 result` to this file, in the shape the stage 1 result uses: the footprint table first because it is citable, then the tests, then the benchmark numbers with the conditions that disqualify them if they are scouting figures, then a closing paragraph on what the stage bought and what it cost. State at minimum: + +- the fresh chunk in objects and bytes, against S1 and S2, under both header modes +- what the declared difference table ended up containing, and every row of Step 2 of Task 9 that had to be corrected against the source +- the materialisation counts from `SectionMaterialisationTest`, including the number for the heightmap gap, with the reason +- the measured price of `Palette#optimize` from Task 5, as a ratio against the commit +- the saving at the counted share of `62,24 %`, which is what may be quoted, and the fact that S7 rests on 441 finished chunks around one spawn and licenses no claim beyond a generated overworld near its spawn + +- [ ] **Step 6: Commit** + +```bash +cd /mnt/projects/oss/onelitefeather/Falco-worktrees/block-storage +git add docs/superpowers/plans/2026-08-02-falco-lazy-sections.md +git commit -m "docs(plan): record what stage 2 measured" +``` + +--- + +## Definition of done + +- [ ] `BlockStorage` distinguishes a caller that may write from one that only reads, and the difference is documented as a contract rather than as a convention +- [ ] `LazySectionBlockStorage` exists, shares one `EMPTY` section between every empty slot of every chunk, and materialises with `new Section()` rather than `EMPTY.clone()` — with a test that proves the materialised section has no light and nothing to send +- [ ] A fresh `FalcoChunk` owns zero sections, zero palettes, zero light carriers, zero `AtomicBoolean` and zero heightmaps, asserted per class rather than in total +- [ ] One block write owns exactly one section, and the heightmap refresh that follows it owns none +- [ ] Sending a chunk owns nothing beyond what the chunk already held +- [ ] A generator owns only the sections it filled, and the palettes it filled end at their minimum width rather than at fifteen bits per entry +- [ ] The price of `Palette#optimize` is measured against the commit it follows, and stated, before it is booked +- [ ] `FalcoChunk` holds one block index map and a counter, and a copied chunk still ticks +- [ ] `ChunkFootprintTest` asserts a declared per-class difference table, four injected defects were used to prove it still bites, and no assertion in it is a byte tolerance +- [ ] `FalcoChunkEquivalenceTest` in `falco-benchmarks` passes over all eighteen fixtures — every position and both heightmaps of every column +- [ ] `falco-instance`, `falco-light`, `falco-anvil` and `falco-benchmarks` tests all pass, with the test counts recorded against the stage 1 result +- [ ] Every new public type carries `@ApiStatus.Experimental`, `@author`, `@version` and `@since 0.4.0`; every modified type has its `@version` raised + +## What stage 2 deliberately does not do + +Named here so that a reviewer does not read them as omissions. + +**It does not remove the last `AtomicBoolean` (US-2.05, partially).** The flyweight removes the send flags of every empty section, which is all forty-eight of them for a fresh chunk and the great majority of them for a generated one. The two per materialised section stay. Removing them would mean handing Minestom a `Light` implementation of Falco's own, and that cannot be done: `LightCompute#compute` and `LightCompute#getLight` are package-private, so a foreign carrier can reproduce the storage shape of `SkyLight` and `BlockLight` but not their algorithm — `SectionAllocationBenchmark` states this in as many words and its own replicas refuse both calculate methods for exactly that reason. A carrier that wrapped a real one to fold only the flag would add an object per section and remove one, which is not a saving. Task 9 pins the count so that it cannot grow back unnoticed. + +**It does not remove the chunk `UUID` (US-2.08).** `Chunk.java:47` declares `private final UUID identifier` and `Chunk.java:65` assigns it in the constructor every subclass calls. A subclass cannot delete a field of its superclass, and `Instance` is typed on `Chunk` throughout, so not extending it is not on the table either. Task 9 measures what it costs instead of leaving the story open. + +**It does not stop the heightmap from materialising sections below the terrain.** `Heightmap#refresh(int, int, int)` reaches its sections through `Chunk#getSection(int)` and ends in a `private` setter over a `private` array, so it can be neither overridden nor bypassed. The scan that *starts* a refresh is replaced (Task 3) because it is a `public static` method taking the chunk, and that one is the expensive half — it walks the empty top of the chunk. The column descent below the highest non-empty section is not replaced, and `SectionMaterialisationTest` states what it costs in a world with a gap. + +**It does not touch `FalcoInstance`'s structure.** No facade split, no `ChunkRegistry`, no `ChunkLifecycle`, no lifecycle listeners, no viewer cache cleanup, no primitive chunk index. Those are stage 3. The only change to `FalcoInstance` here is the generator commit, and it is there because a generator is what fills a chunk and therefore what decides whether a lazy layout survives contact with a world. + +**It does not build a shared instance.** That is stage 4, and it rests on US-1.05, which stage 1 delivered. + +**It does not replace `Palette`.** `public sealed interface Palette permits PaletteImpl` is closed by the verifier, and the break-even measurement puts Minestom's choice of representation between 192 and 224 entries, which is sound. What this stage does with palettes is call the method Minestom already has and never calls. + +## What optimize() costs + +Measured by `GeneratorCommitBenchmark` (Task 5), committed as `f790f0d`. AMD Ryzen 7 5800X, 16 hardware threads, JDK 25.0.3 Temurin, `-Xms2g -Xmx2g`, 3 forks × 5 × 1 s warmup × 5 × 1 s measurement, 15 samples per point, `-prof gc`. The machine was **not** idle — an IntelliJ session and a file indexer were running, load average 5.4 rising to 7.0 across the run. The error bars below are JMH's and are tight; the absolute microseconds still carry that load and should be read as a ratio rather than as a wall clock figure for a quiet server. + +One chunk, 24 overworld sections, block palettes only. + +| distinct states | `commitPlain` | `commitOptimized` | ratio | `optimizeAlreadyPacked` | width staged → packed | +|---|---|---|---|---|---| +| 1 | 0.044 ± 0.001 µs | 0.049 ± 0.002 µs | **1.1×** | 0.047 ± 0.003 µs | 0 → 0 | +| 64 | 22.637 ± 1.280 µs | 545.602 ± 20.449 µs | **24.1×** | 285.788 ± 8.994 µs | 15 → 6 | +| 1024 | 23.108 ± 3.123 µs | 529.288 ± 12.895 µs | **22.9×** | 534.017 ± 15.703 µs | 15 → 15 | + +Allocation, `gc.alloc.rate.norm`, same run: `commitPlain` 196 992 B/op at both 64 and 1024 states; `commitOptimized` 336 203 B/op at 64 and 393 259 B/op at 1024. The optimisation therefore adds **139 kB/op** where it narrows and **196 kB/op** where it does not. + +**The decision: Task 6 adds it, and skips nothing.** `optimize()` costs about **0.5 ms per generated chunk**, a little over twenty times the commit it follows. Against S7's census of 441 chunks around one spawn that is roughly 0.23 s of one-off CPU for the whole spawn area, paid on the generation path and never again. For that price a section whose content fits an indirect palette goes from 15 bpe to 6, which is the conversion S9 priced at 203 840 against 84 800 B. The cost is real and is hereby booked; US-2.03 stays a Must and now has its number. + +**Three findings that change what Task 6 may claim.** + +1. **The uniform case is free, not cheap.** At one distinct state the generator has already left the palette in single value mode — `PaletteImpl#setAll` sends a constant supplier to `fill(fillValue)` — and `optimize` returns on its opening `bitsPerEntry == 0`. 0.049 against 0.044 µs. Task 6 must not describe the optimisation as costing something on every chunk; on flat and on empty sections it costs nothing. + +2. **Above 256 distinct states per section the optimisation charges full price and returns nothing.** `PaletteImpl#downsizeWithPalette` opens with `if (newBpe >= bpe || newBpe > maxBitsPerEntry) return;` and `maxBitsPerEntry` is 8 for blocks. A section holding more than 256 distinct states cannot be narrowed at all, yet `optimize` has already walked all 4 096 entries through `getAll` and built an `IntOpenHashSet` over them before it finds out. At 1 024 states `commitOptimized` (529.3 µs) and the control `optimizeAlreadyPacked` (534.0 µs) are the same number within their error bars, and the widths stay at 15 — 506 µs and 196 kB of garbage for zero bytes saved. This is a real hazard for worlds with very heterogeneous sections, and it cannot be cheaply guarded: the walk that would detect it *is* the cost. + +3. **The benchmark had to re-stage its fixture, and the reason is a trap for Task 6 as well.** `MinestomChunks#fill` writes through `Chunk#setBlock`, and a palette grown one block at a time is never more than about a bit wider than its content needs — the survey found 7 → 6 at 64 states, not 15 → 6. A generator does not write that way: `UnitModifier#setAllRelative` ends in `PaletteImpl#setAll`, which calls `makeDirect()` **unconditionally** for any non-constant supplier, without looking at how many distinct values it saw. A generated section is at the direct width because of *how* it was written, not because of *what* it holds, and that — not the block count — is what `optimize` reclaims. `GeneratorCommitBenchmark#widthAGeneratorWouldLeave` reproduces both branches through the only public door to them (`Optimization.SPEED` is `makeDirect`, `Optimization.SIZE` on single-valued content is the `fill`). Measuring the `setBlock` shape and reporting it as the generator shape understated cost and benefit at two of the three points on the axis, and the first draft of this benchmark did exactly that. + +--- + +## Stage 2 result + +Measured 2026-08-02 on branch `feat/block-storage`, against Minestom as pinned by the build and +JDK 25.0.3 (Temurin), legacy object headers of twelve bytes with eight byte alignment +(`falco.compactHeaders=false`), sizes through the JOL instrumentation agent. + +### The footprint, which is citable + +JOL walks a reachable object graph and counts it. That is deterministic, so these figures hold +despite the machine having been under load throughout. + +| | objects | bytes | +| --- | ---: | ---: | +| fresh chunk, `DynamicChunk` | 192 | 6 848 | +| fresh chunk, `FalcoChunk` | **25** | **840** | +| difference | **−167** | **−6 008**, or −87.7 % | + +A **filled** chunk saves 104 bytes and nothing more, at every state count and every arrangement from +67 kB to 230 kB. That is the honest shape of this stage: the flyweight pays for sections that hold +nothing, and a chunk whose sections all hold something has none of those. The 62.24 % empty share +measured in a real generated overworld is what decides how much of the −6 008 a running server sees, +and that share is itself a measurement of 441 finished chunks around one spawn — not a general claim. + +The instance-side cost is unchanged by this stage: 185 B per chunk for an `InstanceContainer`, +161 B for a `FalcoInstance`. + +### What materialises, and when + +From `SectionMaterialisationTest`, counted rather than timed: + +| operation | sections materialised | +| --- | ---: | +| fresh chunk | 0 | +| pure read pass | 0 | +| one `setBlock` at y=64 | 10 | +| serialising a fresh chunk into a packet | 1 | +| `getSection(4)` | 1 | +| `getSections()` | 24 | +| generation of y=−64..0 | 4 of 24 | +| building a heightmap | 0 | +| **first `Heightmap#getHeight` on a fresh chunk** | **24** | +| write order y=200 then y=−64 | 18 | +| the same two writes in the opposite order | 3 | + +Two of these deserve to be read twice. The **heightmap descent is the dominant driver**, not the +block write — a single `setBlock` costs ten sections, almost all of them through +`getHighestBlockSection` walking down from the build limit. And the **write order is worth a factor +of six**, which is a property of the storage that no API expresses and that a caller can only exploit +if it is told. + +The last line of the first table is the one this stage did *not* fix: `Heightmap#getHeight` still +materialises all twenty-four on a fresh chunk, because Minestom's own fallback walks +`Chunk#getSection`. Building the heightmap is free now; asking it a question is not. + +### What `optimize()` costs — a trade, not a win + +`GeneratorCommitBenchmark`, µs per chunk of 24 sections, at 1 / 64 / 1 024 distinct states: + +| arm | 1 | 64 | 1 024 | +| --- | ---: | ---: | ---: | +| `commitPlain` | 0.044 | 22.0 | 26.3 | +| `commitOptimized`, unconditional | 0.049 | 576.7 | 529.8 | +| `commitGuarded`, asks first | 0.049 | **714.0** | **185.1** | +| `packAlreadyPacked` | 0.047 | **31.8** | 176.1 | + +The guard costs **24 % more** where `optimize()` genuinely narrows a palette, and saves **2.9×** +above the indirect limit and **8.5×** on palettes that are already packed. It is worth having because +the unconditional call charges full price for nothing above 256 distinct states per section — +`downsizeWithPalette` gives up when the required width exceeds `maxBitsPerEntry = 8`, but only after +walking all 4 096 entries to find out. + +**These timings are not citable.** One fork of a scouting configuration on a machine at load 4.4 to +7.0. They establish direction and rough magnitude, nothing finer. `docs/benchmarks/full-run.sh` has +still never run. + +### What the footprint comparison cannot see + +Task 9 replaced a single asserted number with a declared per-class difference table, then attacked it +with seven injected defects. Six were caught by name. **The seventh was a `boolean` field on +`FalcoChunk`**, which adds no object and fits into padding the object already carries — it changes +neither the object count nor the shallow size, so nothing in this comparison can observe it. That +limit is now stated in the test's own javadoc rather than left for someone to discover. + +A second honesty note the test prints itself: proving the two chunks equivalent is not free on a lazy +chunk. The equivalence check leaves the fresh Falco chunk at 36 objects and 2 168 bytes, against 25 +and 840 before it — both heightmaps and the one section the descent materialised. The check runs +after the measurement, so it lands outside the tables, and saying so is cheaper than someone later +finding a discrepancy and mistrusting the numbers. + +### Tests + +`:falco-instance:` 143, `:falco-anvil:` 193, `:falco-light:` 189, `:falco-demo:` 139, +`:falco-benchmarks:` 38 — all green, none skipped. `ChunkFootprintTest` is green again after having +been deliberately red since stage 1. + +### What stage 2 did not do + +No off-heap storage, no replacement of `Palette`, no facade split of `FalcoInstance`, no shared +instance — those are stages 3 and 4, or explicit non-goals of the spec. And within its own scope it +leaves the heightmap descent standing: the largest single materialisation driver is Minestom code +this stage chose not to reach into. diff --git a/docs/superpowers/specs/2026-08-01-falco-instance-chunk-design.md b/docs/superpowers/specs/2026-08-01-falco-instance-chunk-design.md new file mode 100644 index 0000000..9f59303 --- /dev/null +++ b/docs/superpowers/specs/2026-08-01-falco-instance-chunk-design.md @@ -0,0 +1,260 @@ +# Design: a chunk, an instance and a shared instance of Falco's own + +Status: proposed · 2026-08-01 + +Requirements follow the OneLiteFeather requirement-engineering standard: user stories per stage, +acceptance criteria in EARS syntax, MoSCoW priorities. The standard normally lives in Outline; this +one lives in the repository because every requirement names a Java type that lives here too. + +## 1. Context + +`falco-instance` today is `FalcoInstance extends Instance` (1 119 lines) and +`FalcoChunk extends DynamicChunk` (129 lines). The chunk **declares no field of its own** — it exists +only to re-expose two `protected` lifecycle hooks and to fix a `copy` that forgets `tickableMap`. +Every byte and every cycle a chunk costs therefore sits outside Falco's control, and the README says +so: *no speed gain is claimed and none is measured*. + +Two structural consequences follow. `FalcoChunk` and `FalcoLightingChunk` both extend `DynamicChunk` +and are therefore **not combinable** — a chunk that wants Falco's lifecycle *and* Falco's light +cannot be built, only copied. And `FalcoInstance` cannot carry a `SharedInstance`, because +`SharedInstance:22` types its field on the concrete `InstanceContainer`. + +This design replaces inheritance with composition at the chunk, gives the instance a container of its +own, and builds a shared instance that repairs the defects of the one Minestom ships. + +## 2. What the measurements establish + +This section is the spine of the design. Every architectural choice below points at a row here. +Figures marked *scouting* come from a `-Pjmh.quick` run (`fork 1`, 3 iterations) and carry no usable +half-width; they establish direction, not magnitude. The full run is pending. + +| # | Finding | Figure | Method | +|---|---|---|---| +| M1 | A fresh chunk, before a single block is set | **6 848 B, 192 objects** | JOL | +| M2 | — of which the section list and everything below it | **5 128 B, 74.9 %** | JOL | +| M3 | — of which both heightmaps, two `short[256]` | **1 120 B, 16.4 %** | JOL | +| M4 | — of which 48 `AtomicBoolean` | 768 B, 11.2 % | JOL | +| M5 | `FalcoChunk` against `DynamicChunk`, all 15 fill variants | **delta 0 B** | JOL | +| M6 | Sharing empty sections instead of allocating 24 | **2 104 against 7 096 B/op, −70 %** | JMH, ±1 B | +| M7 | A generated chunk stays at 15 bpe direct; `optimize()` has no caller in Minestom's main tree | **203 840 against 84 800 B**, factor 2.4 | JOL | +| M8 | Empty section share of a *generated overworld*, finished chunks only | **62.24 %** | census, 441 chunks | +| M9 | — the same world counting unfinished chunks too | 87.48 % | census | +| M10 | — a void hub world, for contrast | 99.61 % | census | +| M11 | Flyweight saving at the measured share | **2 911 B/chunk, 11.4 MB over 4 096** | JOL | +| M12 | Palette break-even, indirect against direct | **between 192 and 224 entries** | JOL | +| M13 | A sorted `int[]` reverse index against fastutil | **16× slower** at 256 entries | JMH, scouting | +| M14 | Viewer cache leak: entries per chunk construction on an `InstanceContainer` | **1, linear, never removed** | unit test | +| M15 | — its cost per copy | 257 B/op, constant across content | JMH, ±0.6 B | +| M16 | A full chunk resend at view distance 10 | **765 ms, 86.5 MB** | JMH, scouting | +| M17 | `setBlock` under 8 threads, disjoint chunks / with a block handler | 6.2× / 7.3× | JMH, scouting | + +Three of these corrected the research that preceded them, and the corrections are the reason the +figures are here rather than the estimates: the flyweight was assumed to act at a 90 % empty share +and acts at 62 % (M8), the 48 `AtomicBoolean` were assumed to be the largest avoidable item and are +a fifth of the sections (M4 against M2), and the sorted reverse index was proposed as an improvement +and is a regression (M13). + +## 3. Goals and non-goals + +**Goals** + +* A chunk that owns its storage, so that M2, M3 and M7 become reachable at all. +* A chunk that is combinable with Falco's light instead of mutually exclusive with it. +* An instance that keeps the lock granularity it already has (M17) and does not inherit M14. +* A shared instance with per-instance state, repairing the aliasing defects of Minestom's. +* Splitting `FalcoInstance` along its responsibilities, so that its lifecycle steps become testable + and measurable individually. + +**Non-goals** + +* **Replacing `Palette`.** `public sealed interface Palette permits PaletteImpl` is closed by the + verifier, and M12 says Minestom's choice of representation is sound anyway. +* **Removing the instance monitor from a container that carries a shared instance.** See §4.4 — it + cannot be done safely, and the reason is a `private` modifier in a foreign class. +* **Off-heap section storage.** A footprint trade, not a CPU gain; `Arena.ofShared().close()` is a + global handshake and a chunk is touched by loader, tick and network threads. +* **Any preview or incubator language feature.** Vector API is still incubating and would force + `--add-modules` on every consumer of a published library; structured concurrency and stable values + are preview; value classes do not exist in 25 at all. + +## 4. Architecture + +### 4.1 Bridge: the chunk stops inheriting its storage + +A new chunk type extends `Chunk` — `public abstract`, with `getSections()` and `getSection(int)` +abstract — and holds a `BlockStorage` as its implementation side. Lifecycle, viewers and packet +building stay on the abstraction side; the memory layout becomes replaceable without touching a chunk +class. Two inheritance branches that could not be combined become two parts that compose. + +Minestom's `Section` and `PaletteImpl` are **not** replaced. They are materialised lazily at the three +boundaries that demand them: packet serialisation, the light engine, and the anvil writer. The saving +of M6 lives inside those boundaries. The cost is stated rather than hidden: any caller of +`getSection` or `getSections` forces materialisation, so the saving is one on the block accessor +path, not one that survives an arbitrary caller reaching into the chunk. + +### 4.2 Storage: flyweight, and the item nobody counted + +Empty sections point at one process-wide `EMPTY` and materialise on first write (M6, M11). The +materialisation allocates a fresh section rather than cloning the flyweight, because `Section#clone` +rebuilds light through `skyLight.set(...)` and would install valid-looking light on a section that has +none. + +Then, in order of measured size: heightmaps allocated lazily (M3 — the second largest item, and one +the preceding research never listed), the 48 flags folded into one packed field (M4), `tickableMap` +dropped as a subset of `entries` with identical keys and identical references, and the chunk `UUID` +removed — `grep getIdentifier` finds only its declaration in all of Minestom. + +Larger than all of those together: **calling `optimize()` once after generation** (M7). + +### 4.3 Instance: keep what works, fix what leaks + +`FalcoInstance` already holds the chunk write lock across the write and runs `updateNeighbours`, +`sendPacketToViewers` and `EventDispatcher.call` after releasing it, where `InstanceContainer` holds +the monitor of the whole instance across all three and across arbitrary `BlockHandler` code (M17). It +already uses a `ConcurrentHashMap` where Minestom's `changingBlockLock` guards nothing — `clear()` +from `tick()` races `put`/`get` under a different lock. Both stay. + +Added: the viewer cache entry is **removed on unload**. Falco escapes the growth of M14 only because +it is not an `InstanceContainer` and receives the `List.of()` singleton; it never clears the entry +either, and one entry per chunk position survives for the life of the process. + +Also added, and explicitly **not** sold as a performance change: a primitive chunk index map instead +of `ConcurrentHashMap`. The boxing is real; the cost is not established, because +`getChunk` is reached on chunk change rather than per block — the `ChunkCache` memoises in between. + +`FalcoInstance` is split behind a thin facade into `ChunkRegistry`, `ChunkLifecycle`, `BlockWriter` +and `ChunkPersistence`. The concrete gain is testability: `publishChunk` and `completeLoad` are +`private` today and reachable only through a full load. The facade must hold no state of its own, or +it is the same class with delegation in front of it. + +### 4.4 Shared instance: built here, and honest about one wall + +`FalcoSharedInstance extends SharedInstance`. Nothing in `SharedInstance` is `final`, so every +delegating method can be replaced; and `areLinked` compares `getInstanceContainer()` rather than +testing for a specific class, so a subclass keeps the fast path that avoids a full resend. M16 is +what makes that worth insisting on: 765 ms and 86.5 MB against zero. + +Repaired: `setGenerator`, `setChunkSupplier` and `enableAutoChunkLoad` keep per-instance state instead +of aliasing the container, and `saveInstance` persists this instance's tags instead of silently +persisting the container's (`InstanceContainer:293` passes `this`). + +**The wall:** the block owner must be an `InstanceContainer`, and its monitor cannot be removed. +`UNSAFE_setBlock` is `private synchronized` with five call sites — `:135` from `setBlock`, `:223`, +`:250`, and `:756` from the neighbour update. Overriding `setBlock` bypasses one of them and leaves +the rest on the private path: two write paths over the same data, one synchronised and one not. That +is a race of our own making. Shared worlds therefore pay the monitor and keep the chunk-level gains; +a world that needs throughput uses `FalcoInstance` without sharing. + +### 4.5 Lifecycle: listeners instead of template methods + +`ChunkLifecycleListener` with `onLoad`, `onPublish`, `onTick` and `onUnload` replaces the four hooks +`FalcoLightingChunk` occupies by inheritance. Today a second extension beside light is impossible. +The event is built lazily, so that zero listeners cost nothing. + +## 5. Stages + +Storage first, because §2 puts nearly every byte there, and shared last, because it depends most on +the storage model. + +| Stage | Content | Depends on | +|---|---|---| +| 1 | `BlockStorage` and the bridge chunk, without the flyweight | — | +| 2 | Flyweight, lazy heightmaps, packed flags, `optimize()` after generation | 1 | +| 3 | Facade split of `FalcoInstance`, viewer cache cleanup, lifecycle listeners | 1 | +| 4 | `FalcoSharedInstance` | **US-1.05** | + +Stage 4 rests on US-1.05 rather than on stage 3: a shared instance needs its block owner to be an +`InstanceContainer` (§4.4), so the Falco chunk has to work inside one before a shared instance can be +built over it. That is why US-1.05 is a Must and not the convenience it reads like. + +**Two corrections, made while planning stage 1.** Both were requirements placed in a stage that +cannot satisfy them, and both moved rather than being weakened. + +*Combining the lifecycle with Falco's light* was a stage 1 story. The bridge alone does not achieve +it, because `FalcoLightingChunk` still extends `DynamicChunk` and the combination needs the listener +stage 3 introduces. It is now US-3.06. + +*Producing Minestom's types only at the boundary* was also a stage 1 story, and stage 1 does the +opposite on purpose: its storage holds sections eagerly so that the chunk measures identical to +`DynamicChunk` and the bridge is proven free before anything moves. Holding none is what the +flyweight buys, so the requirement is now US-2.09. + +Stage 1 buys the seam the later stages need. It delivers no saving, and it must not appear to. + +## 6. User stories + +### Stage 1 — storage behind a bridge + +| ID | Story | Acceptance criterion (EARS) | API | Priority | +|---|---|---|---|---| +| US-1.01 | As a developer I want a chunk that owns its storage, so that its memory layout is mine to change | While a chunk is loaded, shall every block read and write reach `BlockStorage` rather than an inherited section list | `BlockStorage` | Must | +| US-1.03 | As a developer I want equivalence proven against `DynamicChunk`, so that a faster number never comes from computing something else | When a comparison benchmark starts, shall it verify all `16·16·16·sectionCount` positions and both heightmaps and abort the trial on any difference | `MinestomChunks#assertSameBlocks` | Must | +| US-1.05 | As an operator I want the chunk usable inside a plain `InstanceContainer`, so that shared worlds are possible at all | When `setChunkSupplier` is given the Falco chunk, shall a container load and unload it correctly | `InstanceContainer#setChunkSupplier` | Must | + +### Stage 2 — the memory that §2 measured + +| ID | Story | Acceptance criterion (EARS) | API | Priority | +|---|---|---|---|---| +| US-2.01 | As an operator I want empty sections shared, so that a world costs what its terrain costs | While a section holds nothing but air, shall the chunk hold no section object of its own for it | `BlockStorage` | Must | +| US-2.02 | As an operator I want the first write to a shared section to be affordable | When a block is written into a shared empty section, shall the chunk materialise exactly that one section and leave the others shared | `BlockStorage` | Must | +| US-2.03 | As an operator I want generated chunks to shrink, so that generation does not cost 2.4× forever | When a generator has finished a chunk, shall the instance optimise its palettes before the chunk is published | `Palette#optimize` | Must | +| US-2.04 | As a developer I want heightmaps allocated on demand | While no heightmap has been requested or refreshed, shall the chunk hold no heightmap array | `Chunk#motionBlockingHeightmap` | Should | +| US-2.05 | As a developer I want the flags packed | While a chunk exists, shall it hold at most one object carrying the per-section send flags | — | Should | +| US-2.06 | As a developer I want the duplicate tickable map gone | When a block with a handler is placed or removed, shall exactly one map be updated | — | Should | +| US-2.07 | As a developer I want reading an empty section to be no slower than today | When a read reaches a shared empty section, shall it return without touching a palette | `BlockStorage` | Must | +| US-2.09 | As a developer I want Minestom's types produced only at the boundary, so that the saving is not undone internally | When `getSection` is called, shall the chunk materialise a Minestom `Section` and, while it is not called, shall it hold none for an empty section | `Chunk#getSection` | Must | +| US-2.08 | As a developer I want the chunk `UUID` gone, since nothing reads it | While a chunk exists, shall it hold no identifier that no caller consumes | `Chunk#getIdentifier` | Could | + +### Stage 3 — instance, structure and the leak + +| ID | Story | Acceptance criterion (EARS) | API | Priority | +|---|---|---|---|---| +| US-3.01 | As an operator I want unloading to leave nothing behind, so that a long-running server does not grow | When a chunk is unloaded, shall its viewer cache entry be removed | `EntityTracker#viewable` | Must | +| US-3.02 | As a developer I want the instance split along its responsibilities, so that its steps can be tested one at a time | When a chunk is published, shall that step be reachable and assertable without driving a full load | `ChunkLifecycle` | Must | +| US-3.03 | As a developer I want more than one lifecycle extension | When two listeners are registered, shall both be notified on every transition | `ChunkLifecycleListener` | Must | +| US-3.06 | As a developer I want the chunk combinable with Falco's light, so that I do not have to choose | When both the lifecycle and the light extension are installed, shall a single chunk instance serve both | `ChunkLifecycleListener` | Must | +| US-3.04 | As a developer I want no cost when nothing listens | While no listener is registered, shall a lifecycle transition allocate nothing | `ChunkLifecycleListener` | Should | +| US-3.05 | As a developer I want the chunk index unboxed | When a chunk is looked up, shall no `Long` be allocated | — | Could | + +### Stage 4 — shared instance + +| ID | Story | Acceptance criterion (EARS) | API | Priority | +|---|---|---|---|---| +| US-4.01 | As an operator I want the resend fast path kept, since a resend costs 765 ms | When a player moves between a shared instance and its container, shall `areLinked` report them linked | `SharedInstance#areLinked` | Must | +| US-4.02 | As a developer I want per-instance generators, so that one shared world does not reconfigure another | When `setGenerator` is called on a shared instance, shall no other instance observe the change | `Instance#setGenerator` | Must | +| US-4.03 | As an operator I want my tags persisted | When `saveInstance` is called on a shared instance, shall that instance's tags be written | `Instance#saveInstance` | Must | +| US-4.04 | As a developer I want the monitor limitation documented rather than worked around | While a shared instance is in use, shall the documentation state that writes serialise on the container | — | Must | + +## 7. Non-functional requirements + +| ID | Category | Requirement (EARS) | Priority | +|---|---|---|---| +| NFR-001 | Compatibility | The modules shall compile and run against the pinned Minestom version without reflection, `--add-opens` or an open module. | Must | +| NFR-002 | Compatibility | The modules shall use only language and JDK features that are final in Java 25; no preview and no incubator feature shall be required to build or run. | Must | +| NFR-003 | Measurement | If a performance claim is published, then shall a JMH or JOL measurement in this repository support it, stated with its conditions. | Must | +| NFR-004 | Measurement | While a comparison benchmark runs, shall it fail rather than report a number if the two sides disagree on their result. | Must | +| NFR-005 | Correctness | When a chunk read fails, shall the failure reach the caller instead of being reported as an absent chunk. | Must | +| NFR-006 | Concurrency | While a block is written, shall the lock held be the lock of the chunk it touches, not a monitor over the instance. | Must | +| NFR-007 | Memory | The chunk shall allocate no object per block read on any path. | Must | +| NFR-008 | Operations | The chunk shall not require `-XX:+UseCompactObjectHeaders`; where the flag helps, the gain shall be stated per class and measured, never as a percentage. | Should | +| NFR-009 | API | Every new public type shall carry `@ApiStatus.Experimental` while the module is experimental. | Must | + +## 8. Open questions and risks + +| Question / risk | Status | +|---|---| +| The full JMH run is pending; M13, M16 and M17 rest on scouting figures without usable half-widths. Direction is established, magnitude is not. | open | +| M8 rests on 441 finished chunks around one spawn. An ocean or a mountain range would give a different share, and the flyweight's value moves with it. | open | +| Materialisation at the three boundaries may undo the saving for workloads that call `getSection` often. No workload has been measured for how often that happens. | open | +| `optimize()` after generation costs time that has not been measured against the generation itself. | open | +| Whether the facade split can stay thin, or whether it re-accumulates state, can only be judged once written. | open | + +## 9. Acceptance criteria + +- [ ] A chunk exists that holds its own storage and passes position-by-position equivalence against `DynamicChunk` +- [ ] Falco's lifecycle and Falco's light are installed on one chunk instance at the same time +- [ ] A JOL measurement shows the footprint of a chunk at the measured empty share, with and without compact object headers +- [ ] The viewer cache of an instance does not grow across a load/unload cycle +- [ ] `publishChunk` and `completeLoad` are reachable in a test without driving a full load +- [ ] A shared instance keeps its own generator, chunk supplier and tags, and `areLinked` reports it linked +- [ ] Every figure quoted in the README or the wiki names the benchmark that produced it and the configuration it ran under diff --git a/falco-archunit/src/test/java/net/onelitefeather/falco/architecture/ForeignCouplingTest.java b/falco-archunit/src/test/java/net/onelitefeather/falco/architecture/ForeignCouplingTest.java index 7c3aeb8..e7ca831 100644 --- a/falco-archunit/src/test/java/net/onelitefeather/falco/architecture/ForeignCouplingTest.java +++ b/falco-archunit/src/test/java/net/onelitefeather/falco/architecture/ForeignCouplingTest.java @@ -45,7 +45,7 @@ class ForeignCouplingTest { private static final String LIGHT_BOUNDARY = "net\\.onelitefeather\\.falco\\.light\\." + "(ChunkLightService|ChunkLightArea|ChunkLightScheduler" - + "|FalcoLightingChunk|MinestomBlockLightSource)(\\$.*)?"; + + "|FalcoLightingChunk|ChunkLightListener|MinestomBlockLightSource)(\\$.*)?"; private static final String ANVIL_MINESTOM_BOUNDARY = "net\\.onelitefeather\\.falco\\.anvil\\." @@ -81,13 +81,19 @@ class ForeignCouplingTest { * {@code ChunkLightService$NeighbourhoodEntry} and {@code ChunkLightArea$Entry} both carry a * {@code net.minestom.server.instance.Chunk} as a component. The cost of that is honest — every * nested type of a boundary class is exempt too, whether it needs to be or not. + * + *

{@code ChunkLightListener} is the sixth name on the list and it did not widen the boundary, + * it split one of its members: the three reports it carries were three overrides of + * {@code FalcoLightingChunk}, which was already exempt. It takes a + * {@code net.minestom.server.instance.block.Block} because + * {@code ChunkLifecycleListener#onBlockChange} hands it one. */ @ArchTest static final ArchRule lightCoreKnowsNoMinestom = noClasses() .that().resideInAPackage(LIGHT).and().haveNameNotMatching(LIGHT_BOUNDARY) .should().dependOnClassesThat().resideInAnyPackage("net.minestom..") .because("propagation has to stay verifiable without a running server and work with any " - + "chunk implementation; only those five classes are the boundary"); + + "chunk implementation; only those six classes are the boundary"); /** * F2 — {@code RegionFile} reads no registry, and that is the precondition of the published diff --git a/falco-archunit/src/test/java/net/onelitefeather/falco/architecture/ModuleBoundaryTest.java b/falco-archunit/src/test/java/net/onelitefeather/falco/architecture/ModuleBoundaryTest.java index 501ba4e..3a61992 100644 --- a/falco-archunit/src/test/java/net/onelitefeather/falco/architecture/ModuleBoundaryTest.java +++ b/falco-archunit/src/test/java/net/onelitefeather/falco/architecture/ModuleBoundaryTest.java @@ -28,11 +28,14 @@ * Guards the promise that {@code falco-anvil}, {@code falco-light} and {@code falco-instance} are * three separately pullable artefacts, each of which can be taken without the other two. * - *

Nothing in the build enforces this. None of the three modules declares a {@code project} - * dependency on another, so the compiler never sees a cross-module import and cannot reject one; a - * single {@code import} plus a single line in a build file would silently turn three artefacts into - * one. The same holds for the surface towards third parties: Minestom, adventure-nbt, annotations - * and fastutil are {@code compileOnly} everywhere and never reach the published POM, so an + *

Nothing in the build enforces this. Exactly one {@code project} dependency between the three + * exists — {@code falco-light} sees {@code falco-instance}, {@code compileOnly}, so that + * {@code FalcoLightingChunk} can be a {@code FalcoChunk}; see + * {@link #onlyTheChunkOfTheLightModuleKnowsTheInstanceModule} for what keeps it from spreading. Every + * other direction is unenforced by the compiler, so a single {@code import} plus a single line in a + * build file would silently turn three artefacts into + * one. The same holds for the surface towards third parties: Minestom, adventure-nbt, annotations, + * fastutil and flare are {@code compileOnly} everywhere and never reach the published POM, so an * accidental new {@code implementation} dependency is invisible inside this repository and lands on * every Minestom server that pulls one of the artefacts. * @@ -84,10 +87,9 @@ private static ArchRule isolated(String self, String... foreign) { * *

{@code Installation.md:14} promises "take one without the other if that is all you need", * and the build backs that up only by omission: no module declares a {@code project} dependency - * on another, so the first cross-module import compiles happily and breaks the promise - * silently. The independence costs something and is paid anyway, see - * {@code ServerStack.java:27-40}, which argues at length why {@code FalcoInstance} and - * {@code FalcoLightingChunk} cannot be combined instead of marrying the two modules. + * on {@code falco-anvil}, so the first cross-module import compiles happily and breaks the + * promise silently. The loader is the one of the three that genuinely needs nothing from the + * other two: a world is read the same way whether the chunks it fills are Minestom's or Falco's. * *

{@code .demo} and {@code .benchmark} are forbidden targets as well: a published module * reaching into unpublished code would not even resolve for a consumer. @@ -96,16 +98,59 @@ private static ArchRule isolated(String self, String... foreign) { static final ArchRule anvilIsStandalone = isolated(ANVIL, LIGHT, INSTANCE, DEMO, BENCH); /** - * M1: {@code falco-light} knows neither of the other modules. + * M1: {@code falco-light} knows neither {@code falco-anvil} nor the unpublished modules. * - *

This is the concrete temptation of the three. {@code LightUpdateAware} and - * {@code ChunkLightScheduler} form an interface that {@code FalcoChunk} could serve, and a - * single import of {@code FalcoChunk} in {@code ChunkLightArea} would force the instance module - * onto every user of the light engine, for a convenience that has an interface-shaped - * alternative. + *

{@code falco-instance} is no longer among the forbidden targets, and that is US-3.06 rather + * than a relaxation of M1. {@code FalcoLightingChunk} is a {@code FalcoChunk} now, because the + * alternative was the state this repository was in for three stages: two chunk types with one + * superclass slot between them, so Falco's light and Falco's lifecycle could be copied together + * but never built together. A chunk cannot be a {@code FalcoChunk} without the module that + * defines it, so one of the two modules had to see the other, and this is the direction that + * costs a consumer nothing they did not ask for. + * + *

What replaces the blanket ban is {@link #onlyTheChunkOfTheLightModuleKnowsTheInstanceModule} + * below, which keeps the engine itself free of it. The dependency is {@code compileOnly} in + * {@code falco-light/build.gradle.kts}, so it reaches no published POM and no consumer of the + * bare engine. + */ + @ArchTest + static final ArchRule lightIsStandalone = isolated(LIGHT, ANVIL, DEMO, BENCH); + + /** + * The two classes of {@code falco-light} whose job is to be, or to serve, a {@code FalcoChunk}. + * + *

Named rather than derived, because the point of the rule is that this list stays at two. + * The trailing {@code (\$.*)?} covers an anonymous or nested class either of them may grow, which + * javac emits under the outer name. + */ + private static final DescribedPredicate THE_CHUNK_SIDE_OF_THE_LIGHT_MODULE = + nameMatching("net\\.onelitefeather\\.falco\\.light\\." + + "(FalcoLightingChunk|ChunkLightListener)(\\$.*)?") + .as("the chunk side of the light module") + .forSubtype(); + + /** + * M1b: inside {@code falco-light}, only the chunk and its listener may see {@code falco-instance}. + * + *

This is the concrete temptation the old blanket rule guarded against, and it survives the + * edge unchanged. {@code LightUpdateAware} and {@code ChunkLightScheduler} form an interface that + * {@code FalcoChunk} could serve directly, and a single import of {@code FalcoChunk} in + * {@code ChunkLightArea} or {@code ChunkLightService} would put the instance module on the + * classpath of every user of the light engine — including the ones running a plain + * {@code InstanceContainer}, for whom {@code compileOnly} means the class is simply not there. + * + *

{@code ChunkLightScheduler} is deliberately not exempt even though its {@code supplier()} + * hands out a {@code FalcoLightingChunk}: a method reference to a constructor is a dependency on + * that class alone, not on its supertype, which is what keeps the scheduler loadable without + * {@code falco-instance} present. */ @ArchTest - static final ArchRule lightIsStandalone = isolated(LIGHT, ANVIL, INSTANCE, DEMO, BENCH); + static final ArchRule onlyTheChunkOfTheLightModuleKnowsTheInstanceModule = noClasses() + .that().resideInAPackage(LIGHT) + .and(not(THE_CHUNK_SIDE_OF_THE_LIGHT_MODULE)) + .should().dependOnClassesThat().resideInAPackage(INSTANCE) + .because("falco-instance is compileOnly here, so every other class of this module has to " + + "keep loading and running on a server that never pulled it"); /** * M1: {@code falco-instance} knows neither of the other modules. @@ -125,12 +170,30 @@ private static ArchRule isolated(String self, String... foreign) { * package name is empty, and an empty package name matches none of the patterns above. Listing * the three Falco packages here is only safe because M1 already forbids every dependency * between them. + * + *

Why flare is on this list

+ *

{@code space.vectrix.flare} joined for {@code ChunkRegistry}, whose chunk map is a + * {@code Long2ObjectSyncMap} so that a lookup does not box its index. It qualifies on the same + * two counts fastutil does, and both were checked rather than assumed. It is + * {@code compileOnly} in {@code falco-instance}, so it is absent from the published POM — + * {@code :falco-instance:generatePomFileForMavenPublication} lists {@code slf4j-api} and + * nothing else. And it is present at runtime wherever Minestom is, because Minestom depends on + * it and merely hides it from its own compile classpath: + * {@code :falco-instance:dependencies --configuration compileClasspath} prints no flare while + * {@code --configuration testRuntimeClasspath} prints {@code flare:2.0.1} and + * {@code flare-fastutil:2.0.1}. + * + *

That second half is the load-bearing one and it is a version pin, not a guarantee: the + * catalog names 2.0.1 because that is what Minestom resolves to today. A Minestom bump that + * moves flare has to move {@code version("flare", ...)} in {@code settings.gradle.kts} with it, + * or {@code falco-instance} compiles against one flare and runs against another. */ private static final DescribedPredicate ALLOWED_DEPENDENCY = resideInAnyPackage(ANVIL, LIGHT, INSTANCE, "java..", "net.minestom..", "net.kyori.adventure.nbt..", "net.kyori.adventure.key..", - "it.unimi.dsi.fastutil..", "org.slf4j..", "org.jetbrains.annotations..") + "it.unimi.dsi.fastutil..", "space.vectrix.flare..", + "org.slf4j..", "org.jetbrains.annotations..") .or(describe("a primitive", JavaClass::isPrimitive)); /** diff --git a/falco-archunit/src/test/java/net/onelitefeather/falco/architecture/PublicApiTest.java b/falco-archunit/src/test/java/net/onelitefeather/falco/architecture/PublicApiTest.java index d909798..2e4ba17 100644 --- a/falco-archunit/src/test/java/net/onelitefeather/falco/architecture/PublicApiTest.java +++ b/falco-archunit/src/test/java/net/onelitefeather/falco/architecture/PublicApiTest.java @@ -222,15 +222,21 @@ public void check(JavaCodeUnit unit, ConditionEvents events) { /** * A public class is final unless Minestom or the error hierarchy force it open. *

- * Five of the 31 public types are non-final and every one of them is forced: {@code FalcoChunk} - * ({@code falco-instance/.../instance/FalcoChunk.java:50}) and {@code FalcoLightingChunk} - * ({@code falco-light/.../light/FalcoLightingChunk.java:80}) extend {@code DynamicChunk} for its - * protected lifecycle hooks, {@code FalcoInstance} - * ({@code falco-instance/.../instance/FalcoInstance.java:120}) extends {@code Instance} because + * Four of the public types are non-final and every one of them is forced: {@code FalcoChunk} + * ({@code falco-instance/.../instance/FalcoChunk.java}) extends {@code Chunk} for its protected + * lifecycle hooks, {@code FalcoInstance} + * ({@code falco-instance/.../instance/FalcoInstance.java}) extends {@code Instance} because * Minestom branches on {@code instanceof InstanceContainer}, and the two exception types must * stay extensible so a consumer can refine the error hierarchy. *

*

+ * {@code FalcoLightingChunk} used to be the fifth and stopped being forced when it became a + * {@code FalcoChunk} rather than a {@code DynamicChunk}: its superclass is no longer a Minestom + * type, the exemption below no longer covers it, and it is {@code final} today. That is the shape + * this rule is meant to produce — what a subclass of it would have wanted is a lifecycle + * listener, which is an interface. + *

+ *

* The real extension points of this project are interfaces — the benchmarks show it, where * {@code FakeBlockLightSource} implements {@code BlockLightSource} instead of subclassing * {@code ChunkLightService}. An accidentally non-final class in an experimental API without diff --git a/falco-benchmarks/build.gradle.kts b/falco-benchmarks/build.gradle.kts index b25b7e7..1e89713 100644 --- a/falco-benchmarks/build.gradle.kts +++ b/falco-benchmarks/build.gradle.kts @@ -9,29 +9,113 @@ dependencies { jmhImplementation(platform(libs.adventure.bom)) jmhImplementation(project(":falco-anvil")) jmhImplementation(project(":falco-light")) + jmhImplementation(project(":falco-instance")) jmhImplementation(libs.adventure.nbt) jmhImplementation(libs.annotations) jmhImplementation(libs.jmh.core) + jmhImplementation(libs.jol.core) jmhImplementation(libs.minestom) jmhImplementation(libs.fastutil) + jmhImplementation(libs.flare.fastutil) + + testImplementation(platform(libs.mycelium.bom)) + testImplementation(platform(libs.adventure.bom)) + testImplementation(sourceSets["jmh"].output) + testImplementation(project(":falco-anvil")) + testImplementation(project(":falco-instance")) + testImplementation(libs.adventure.nbt) + testImplementation(libs.annotations) + testImplementation(libs.jmh.core) + testImplementation(libs.jol.core) + testImplementation(libs.minestom) + testImplementation(libs.fastutil) + testImplementation(libs.junit.jupiter) + testImplementation(libs.junit.platform.launcher) + testRuntimeOnly(libs.junit.jupiter.engine) } jmh { jmhVersion.set(libs.versions.jmh) includeTests.set(false) resultFormat.set("JSON") - resultsFile.set(layout.buildDirectory.file("reports/jmh/results.json")) - humanOutputFile.set(layout.buildDirectory.file("reports/jmh/human.txt")) val include = providers.gradleProperty("jmh.include").orNull + val quick = providers.gradleProperty("jmh.quick").isPresent + val threads = providers.gradleProperty("jmh.threads").orNull + val forks = providers.gradleProperty("jmh.forks").orNull + val params = providers.gradleProperty("jmh.params").orNull + val resultsPath = providers.gradleProperty("jmh.resultsFile").orNull + val humanPath = providers.gradleProperty("jmh.humanFile").orNull + + if (resultsPath != null) { + resultsFile.set(rootProject.file(resultsPath)) + } else { + resultsFile.set( + layout.buildDirectory.file(if (quick) "reports/jmh/results-quick.json" else "reports/jmh/results.json") + ) + } + + if (humanPath != null) { + humanOutputFile.set(rootProject.file(humanPath)) + } else { + humanOutputFile.set(layout.buildDirectory.file("reports/jmh/human.txt")) + } + + profilers.set(if (providers.gradleProperty("jmh.noProfiler").isPresent) emptyList() else listOf("gc")) if (include != null) { includes.set(listOf(include)) } + + if (quick) { + fork.set(1) + warmupIterations.set(2) + iterations.set(3) + } + + if (threads != null) { + this.threads.set(threads.toInt()) + } + + if (forks != null) { + fork.set(forks.toInt()) + } + + params?.split(';')?.filter { it.isNotBlank() }?.forEach { entry -> + val name = entry.substringBefore('=').trim() + val values = entry.substringAfter('=').split(',').map { it.trim() }.filter { it.isNotEmpty() } + + require(name.isNotEmpty() && values.isNotEmpty()) { + "jmh.params expects name=value[,value][;name=value], got '$entry'" + } + + benchmarkParameters.put(name, objects.listProperty(String::class.java).value(values)) + } } tasks { named("check") { dependsOn(named("compileJmhJava")) } + + withType().configureEach { + val compactHeaders = providers.gradleProperty("falco.compactHeaders").isPresent + val onMacOs = providers.systemProperty("os.name").getOrElse("").startsWith("Mac") + val forceOnMacOs = providers.gradleProperty("falco.macOsFootprintTests").isPresent + + onlyIf("footprint measurement hangs on macOS; see docs/benchmarks/README.md") { + forceOnMacOs || !onMacOs + } + + maxHeapSize = "4g" + jvmArgs("-Djdk.attach.allowAttachSelf=true") + jvmArgs("-XX:+EnableDynamicAgentLoading") + jvmArgs("-Djol.magicFieldOffset=true") + jvmArgs(if (compactHeaders) "-XX:+UseCompactObjectHeaders" else "-XX:-UseCompactObjectHeaders") + systemProperty("falco.compactHeaders", compactHeaders.toString()) + + providers.gradlePropertiesPrefixedBy("falco.census.").get().forEach { (name, value) -> + systemProperty(name, value) + } + } } diff --git a/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/ChunkComparisonBenchmark.java b/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/ChunkComparisonBenchmark.java new file mode 100644 index 0000000..9460924 --- /dev/null +++ b/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/ChunkComparisonBenchmark.java @@ -0,0 +1,869 @@ +package net.onelitefeather.falco.benchmark.instance; + +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.DynamicChunk; +import net.minestom.server.instance.Instance; +import net.minestom.server.instance.InstanceContainer; +import net.minestom.server.instance.block.Block; +import net.minestom.server.instance.heightmap.Heightmap; +import net.onelitefeather.falco.benchmark.support.BenchmarkConstants; +import net.onelitefeather.falco.benchmark.support.MinestomChunks; +import net.onelitefeather.falco.instance.FalcoChunk; +import net.onelitefeather.falco.instance.FalcoInstance; +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.TearDown; +import org.openjdk.jmh.annotations.Warmup; + +import java.util.BitSet; +import java.util.Objects; +import java.util.Random; +import java.util.concurrent.TimeUnit; + +/** + * The {@link ChunkComparisonBenchmark} class measures the chunk of Falco against the chunk of + * Minestom on the four operations a chunk spends its life in, and it is the control that decides + * whether every other chunk measurement of this module means anything. + *

+ * The expected result is not "Falco is faster" but "the two sides are indistinguishable", and that + * is what makes the class valuable: it is the only measurement in this module whose correct answer + * is known in advance, so a bias of the harness has to surface here rather than later, when a + * prototype with its own storage runs against the same scaffolding and the bias would be read as a + * property of the prototype. + *

+ *

+ * Why that answer is known in advance changed with stage 1 of the block storage work, and the change + * is worth stating precisely. {@code FalcoChunk} used to extend {@code DynamicChunk}, declare no + * field of its own and override neither {@code setBlock} nor {@code getBlock} nor the heightmaps, so + * the two arms executed the same bytecode and their equality was a fact about the class hierarchy. + * Today it extends {@code Chunk}, holds a {@code BlockStorage} field and overrides all four. The + * bodies of those overrides are the bodies of {@code DynamicChunk} with the palette access moved + * behind the field, so the two arms still do the same work on the same data — but that is now a + * property somebody maintains rather than one the compiler enforces. + *

+ * + *

Which storage the Falco arm runs on, and why the arms are still comparable on it

+ *

+ * {@code LazySectionBlockStorage}, since stage 2 of the same work made it the default of + * {@code FalcoChunk}. That storage hands out one shared, empty {@code Section} for every section the + * chunk has never written into and only creates a private one on the first write, which is a + * different layout from the one {@code DynamicChunk} has and not the eager + * {@code SectionBlockStorage} this paragraph named while stage 1 was the newest thing on the branch. + *

+ *

+ * It does not cost the comparison, and the reason is a property of the fixture rather than of the + * storage. {@code MinestomChunks#fill} walks {@code y} from the floor of the chunk to its build + * limit and writes a block at every one of the {@code 98304} positions, whatever the shape; the air + * check that follows it refuses a chunk that came out empty. Every section of the Falco arm is + * therefore private and populated before the first measured invocation, and a lazy storage whose + * sections have all been written into holds exactly what an eager one holds. What the two arms + * measure is two full chunks, once through the field of {@code DynamicChunk} and once through the + * seam of {@code FalcoChunk}. + *

+ *

+ * The condition that buys that is also the limit of these numbers and belongs next to them: this + * class only ever measures a fully materialised chunk. It says nothing about what stage 2 was built + * for — a chunk whose empty sections were never created — and no figure from here may be quoted for + * or against that. {@code SectionMaterialisationTest} counts the sections a chunk holds and + * {@code ChunkFootprintTest} weighs them; those two are where the saving is stated. + *

+ *

+ * What follows for a reader of these numbers is that a difference between the arms is no longer + * automatically a defect in the harness. It can still be one, and it can now equally be a finding + * about the chunk — that the seam costs time — and the two have to be told apart before either is + * reported. Two other measurements are what make that possible. + * {@code FalcoChunkEquivalenceTest} shows that both sides hold the same blocks and the same + * heightmaps after exactly these operations, so a difference is not a difference in content, and + * {@code ChunkFootprintTest} weighs the seam, which is a fixed per chunk cost of a field and the + * objects behind it — so a difference that grows with the block count is not the seam whatever that + * test currently reports. What that test may no longer be quoted for is the stage 1 sentence that + * the two chunks retain the same objects: the lazy layout holds fewer, by construction, and the + * per class figures are restated there rather than here. Neither of the two measurements would + * notice a harness that drives the two arms differently, which is why the checks below still exist + * and still abort the trial. + *

+ *

+ * The class deliberately does not live in {@code net.minestom.server.instance}. Two benchmarks of + * this module do, because the members they measure are package-private and unreachable otherwise. + * Nothing here needs that: {@code Chunk#setBlock}, {@code Chunk#getBlock}, {@code Chunk#copy}, + * {@code Chunk#motionBlockingHeightmap()}, {@code Heightmap#refresh(int, int, int)} and + * {@code Heightmap#getHighestBlockSection(Chunk)} are all public. Splitting a package of the server + * across two artifacts is a cost that is only worth paying when there is no other way in, and here + * there is one. + *

+ * + *

The four operations, and why these four

+ *

+ * A chunk is written to, read from, copied and asked for its heightmaps, and those four paths have + * four different cost structures. {@code setBlock} is a palette write plus a hash probe per block + * map plus two incremental heightmap updates — two probes on the Minestom arm, which keeps a second + * map of its tickable blocks, and one on the Falco arm, which keeps a counter instead. + * {@code getBlock} is a palette read behind a guard over the block + * entity map. {@code copy} clones every section, which is the one operation whose cost is dominated + * by allocation rather than by work. The full heightmap refresh is a top-down palette scan over all + * {@code 256} columns and is the most expensive of the four by a wide margin. A candidate storage + * that wins on one of them can easily lose on another — a denser packing usually pays for its + * density in the read, and a lazier section usually pays for its laziness in the first write — so + * an argument built on a single operation would be an argument about whichever operation the author + * happened to pick. + *

+ * + *

Why the writes are scattered and why they are a fixed set

+ *

+ * The fill of the fixture walks the chunk in storage order, which is the order a generator writes + * in and the friendliest order the storage will ever see. Measuring {@code setBlock} the same way + * would measure the generator once more. A player, a plugin and a world edit hit positions that + * share neither a section nor a cache line, so the measured batch is drawn from the whole volume of + * the chunk instead, without repeating a position: a repeated position would be a guaranteed cache + * hit that no scattered access pattern produces, and it would let a later write of the batch undo + * an earlier one. + *

+ *

+ * The batch is built once and then written unchanged on every invocation, with the same block at + * the same position every time. That makes the whole benchmark idempotent after its first pass: the + * chunk reaches a fixed point during warmup and stays there, so the last measured invocation runs + * on exactly the same chunk as the first. A batch of freshly drawn blocks would instead grow the + * palette of a section a little on every pass, and the measurement would slowly drift into + * describing a chunk that no {@code @Setup} ever verified. + *

+ *

+ * Because the fixed point rather than the fill is what gets measured, the batch is applied once + * during the setup and the equality of the two sides is proved again afterwards. The chunk the + * first measured invocation touches is therefore a chunk that has been walked position by position + * and found identical on both arms. + *

+ *

+ * The perturbation this costs is stated rather than hidden. The batch rewrites + * {@value #SCATTER_COUNT} of the {@code 98304} positions of an overworld chunk, roughly four + * percent, which breaks a run of {@link MinestomChunks.FillShape#LAYERED} or + * {@link MinestomChunks.FillShape#RANDOM_RUNS} wherever it lands. The shapes stay clearly distinct + * at that rate, but a reader comparing these numbers against a benchmark that fills and does not + * perturb should know that the arrangement here is the arrangement of the fill plus a four percent + * scatter. + *

+ * + *

Why the state count is exact after the setup

+ *

+ * {@link MinestomChunks.FillShape#LAYERED} cannot show more than {@code 16} states per section and + * therefore no more than {@code 384} over a full height chunk, so a fill asking for {@code 1024} + * states leaves {@code 640} of them unplaced. The scatter batch closes that gap as a side effect: + * it holds {@value #SCATTER_COUNT} distinct positions and cycles through a set of at most + * {@code 1024} blocks, so every block of the set is written at least four times and none of those + * writes can be overwritten by another member of the batch. After the setup every parameter + * combination holds exactly as many distinct states as it asked for, and + * {@link #verifyStateCount()} checks that with an exception rather than trusting it. + *

+ *

+ * What that check cannot do is make the arrangement mean the same thing at that one point. At + * {@code distinctStates == 1024} under {@code LAYERED}, {@code 384} of the states sit as layers and + * the remaining {@code 640} sit as isolated scattered blocks. The point is a legitimate measurement + * of a chunk, it is simply not a measurement of a layered chunk, and a curve drawn through it has + * to say so. + *

+ * + *

Both chunks have to agree before anything is measured

+ *

+ * This module holds a comparison worthless unless it first shows that both sides produce the same + * result, the pattern {@code LightEngineComparisonBenchmark#verifyBothEnginesAgree} established. + * {@link #setUp()} does that twice — once for the fill and once for the fixed point the + * measurements actually run on — through {@code MinestomChunks#assertSameBlocks}, which walks all + * {@code 16 * 16 * 16 * sectionCount} positions plus both heightmaps and throws with the first + * disagreeing position. A throwing setup aborts the trial, which is the point: a number that came + * from comparing two different worlds must never reach the results file. + *

+ *

+ * Three further checks guard the failures that a block walk alone would not catch. + * {@link #verifyArms()} asserts that the two instances really handed out a {@code DynamicChunk} and + * a {@code FalcoChunk}, because a changed chunk supplier on either side would turn the whole + * benchmark into a comparison of a type against itself and would do so while every other assertion + * still passed. {@code MinestomChunks#assertNotAllAir} rejects a chunk whose fill silently did not + * take, which is the failure mode that produces the best numbers this benchmark will ever report + * and reports them for an empty palette. And {@link #tearDown()} repeats that air check after the + * measurements, so a benchmark method that emptied the chunk it was measuring is caught by the same + * rule that would have caught an empty fill. + *

+ * + *

How to read the numbers

+ *

+ * The measured operation of {@link #minestomSetBlock()}, {@link #falcoSetBlock()}, + * {@link #minestomGetBlock()} and {@link #falcoGetBlock()} is the whole batch of + * {@value #SCATTER_COUNT} blocks, not a single block. That is a deliberate departure from an + * {@code @OperationsPerInvocation} split: this module reports in microseconds throughout, and a + * per-block figure would print as five leading zeroes and lose every digit that carries + * information. Divide a reported figure by {@value #SCATTER_COUNT} and multiply by {@code 1000} to + * get nanoseconds per block. {@link #minestomCopy()}, {@link #falcoCopy()}, + * {@link #minestomHeightmapRefresh()} and {@link #falcoHeightmapRefresh()} measure one whole chunk + * operation each, so their figures need no conversion. + *

+ *

+ * {@code gc.alloc.rate.norm} is the second half of the result and for the copy it is the more + * important half: the build enables the {@code gc} profiler for every run, and the claim this + * benchmark exists to support is about bytes as much as about time. The retained size that claim + * also needs is not measurable here — an allocation rate is not a footprint — and is taken by the + * JOL tests of B-01 alongside these runs. + *

+ * + *

Running it

+ *

+ * The full grid is {@code 6 x 3} parameter combinations over the {@code 10} methods of this class, + * of which {@code 8} belong in a baseline; that is {@code 144} scenarios, and at the three forks a + * citable run needs it is {@code 81} minutes of wall clock. The figure is derived from the scouting + * run rather than guessed: {@code 3} forks of {@code 5 + 5} iterations of one second, plus the + * {@code 1,3 s} per fork that run measured for this class, is {@code 33,9 s} a scenario. Both axes + * are worth having, but they are rarely worth having at once: the state count is the axis that + * decides how a palette behaves, and + * the shape is the axis that decides whether a result generalises beyond one kind of world. The + * recommended pair of runs takes the state count under the shape closest to real terrain and the + * shape at the two ends of the state count: + *

+ * 
{@code
+ * ./gradlew :falco-benchmarks:jmhJar
+ * java -jar falco-benchmarks/build/libs/falco-benchmarks-*-jmh.jar "ChunkComparisonBenchmark" \
+ *     -p fillShape=RANDOM_RUNS -f 3 -wi 5 -i 5 -prof gc
+ * java -jar falco-benchmarks/build/libs/falco-benchmarks-*-jmh.jar "ChunkComparisonBenchmark" \
+ *     -p fillShape=UNIFORM,LAYERED -p distinctStates=1,1024 -f 3 -wi 5 -i 5 -prof gc
+ * }
+ *

+ * The full grid, for the run that produces the published table. It is driven by + * {@code docs/benchmarks/full-run.sh}, which is where it belongs rather than in a shell history, + * and it excludes the two arms that may not be quoted: + *

+ * 
{@code
+ * java -jar falco-benchmarks/build/libs/falco-benchmarks-*-jmh.jar "ChunkComparisonBenchmark" \
+ *     -e '\.(minestomCopy|falcoCopy)$' \
+ *     -f 3 -wi 5 -i 5 -prof gc -foe true -rf json \
+ *     -rff docs/benchmarks/baseline-/ChunkComparisonBenchmark.json
+ * }
+ *

+ * The exclusion is anchored at the end of the method name so that {@link #minestomCopyIsolated()} + * and {@link #falcoCopyIsolated()}, the pair whose ratio does mean something, stay in. The two + * excluded arms are run separately, into a file whose name says it is not a baseline; see + * {@code docs/benchmarks/README.md} for what may and may not be taken from that run. + *

+ * + *

Why three forks and not one

+ *

+ * The heap is raised over the {@code 512m} the module uses elsewhere because a server process, two + * instances and two full height chunks live in the fork, and because {@link #minestomCopy()} + * allocates a complete chunk on every invocation. + *

+ *

+ * The fork count was {@code 1}, on the argument that a second fork doubles a startup far more + * expensive than the measurement it precedes. The scouting run of 2026-08-01 measured that startup + * and it is not: twenty four combinations of this class at {@code -f 1 -wi 2 -i 3} took + * {@code 151 s} of wall clock against {@code 120 s} of iterations, which puts the whole start — + * JVM launch, {@code MinecraftServer.init()}, both instances, both chunks and the equality proof of + * {@link #setUp()} — at about {@code 1,3 s} per fork. A fork at the configuration above runs + * {@code 10 s} of iterations, so the start is thirteen percent of it and the argument for a single + * fork does not survive its own measurement. + *

+ *

+ * What one fork does cost is the ability to see anything at all about variance between JVM + * launches, and this project has a documented case of that mattering: a two-thread row of + * {@code RegionFileComparisonBenchmark} in the README did not reproduce on an independent run of + * the identical configuration, moving from a usable interval to a half width {@code 8,3} times its + * own mean. At one fork the {@code +-} JMH prints covers variance between iterations of one launch + * and is silent about the rest. Three is the smallest count at which a disagreeing fork has a + * majority to disagree with, and JMH keeps the per fork raw data in the JSON so it can be read + * rather than guessed at. + *

+ *

+ * {@code -jvmArgs} is not passed. The heap is already in the {@code @Fork} annotation as + * {@code jvmArgsAppend}, and restating it on the command line replaces the inherited base arguments + * rather than adding to them, which is a different JVM than the annotation describes. + *

+ * + * @author TheMeinerLP + * @version 1.4.0 + * @since 0.4.0 + */ +@State(Scope.Thread) +@BenchmarkMode(Mode.AverageTime) +@OutputTimeUnit(TimeUnit.MICROSECONDS) +@Fork(value = 1, jvmArgsAppend = {"-Xms2g", "-Xmx2g"}) +@Warmup(iterations = 5, time = 1) +@Measurement(iterations = 5, time = 1) +public class ChunkComparisonBenchmark { + + /** + * The amount of distinct positions the scattered read and write batches touch. + *

+ * One section worth of positions, spread over the whole chunk rather than over one section. + * The count is large enough that a single invocation crosses every section of a full height + * chunk several times and cannot sit in one cache line, and small enough that a batch stays far + * below the {@code 98304} positions of the chunk, so the measured access pattern stays sparse + * instead of degenerating into a full walk. It matches the batch size of B-14 so the two + * benchmarks can be read against each other. + *

+ */ + public static final int SCATTER_COUNT = 4096; + + /** + * The chunk position both measured chunks are created at. + */ + private static final int CHUNK_POSITION = 0; + + /** + * The amount of distinct block states the measured chunk holds. + *

+ * The lower end is where a palette degenerates: a chunk of one state stores no backing array at + * all. The upper end is above the {@code 964} distinct blocks the registry of the pinned build + * offers, so the fixture falls back to further states of the same blocks there — the two halves + * of a curve drawn over this axis answer a slightly different question and must not be read as + * one. + *

+ */ + @Param({"1", "2", "16", "64", "256", "1024"}) + public int distinctStates; + + /** + * The arrangement the states are written in. + */ + @Param({"UNIFORM", "LAYERED", "RANDOM_RUNS"}) + public MinestomChunks.FillShape fillShape; + + private InstanceContainer container; + private FalcoInstance falco; + private Chunk minestomChunk; + private Chunk falcoChunk; + private int[] scatterX; + private int[] scatterY; + private int[] scatterZ; + private Block[] scatterBlocks; + + /** + * Builds the two chunks, brings them to the state the measurements run on and proves that they + * are identical. + *

+ * The order is the argument of this method. The two instances are built first, then the two + * chunks, then the arms are checked so a changed chunk supplier fails before anything expensive + * happens. Both chunks are filled from the same seed and compared position by position, which + * covers the fixture. The scatter batch is then applied to both and the comparison is repeated, + * which covers the fixed point the measured invocations actually run on. Only then are the two + * anti tautology checks taken, because both of them are statements about the finished state. + *

+ * + * @throws IllegalStateException if the two chunks are not of the expected types, hold different + * content, hold nothing but air or disagree on their state count + */ + @Setup(Level.Trial) + public void setUp() { + MinestomChunks.ensureServer(); + this.container = MinestomChunks.newContainer(); + this.falco = MinestomChunks.newFalcoInstance(); + this.minestomChunk = MinestomChunks.newChunk(this.container, CHUNK_POSITION, CHUNK_POSITION); + this.falcoChunk = MinestomChunks.newChunk(this.falco, CHUNK_POSITION, CHUNK_POSITION); + verifyArms(); + + MinestomChunks.fill(this.minestomChunk, this.distinctStates, this.fillShape); + MinestomChunks.fill(this.falcoChunk, this.distinctStates, this.fillShape); + MinestomChunks.assertSameBlocks(this.minestomChunk, this.falcoChunk); + + buildScatter(); + writeScatter(this.minestomChunk); + writeScatter(this.falcoChunk); + MinestomChunks.assertSameBlocks(this.minestomChunk, this.falcoChunk); + + MinestomChunks.assertNotAllAir(this.minestomChunk); + MinestomChunks.assertNotAllAir(this.falcoChunk); + verifyStateCount(); + } + + /** + * Checks that the measured chunks still hold blocks and releases the two instances. + *

+ * The air check is repeated here rather than only in the setup because the measured operations + * write. A benchmark method that ended up clearing the chunk it measures would report the + * fastest numbers of the whole grid, and nothing in the setup could have seen it. An instance + * that stays registered leaks into every following trial of the fork together with its chunks, + * which is why the release is unconditional. + *

+ * + * @throws IllegalStateException if a measured chunk holds nothing but air afterwards + */ + @TearDown(Level.Trial) + public void tearDown() { + try { + MinestomChunks.assertNotAllAir(this.minestomChunk); + MinestomChunks.assertNotAllAir(this.falcoChunk); + } finally { + MinestomChunks.release(this.container); + MinestomChunks.release(this.falco); + } + } + + /** + * Measures a scattered batch of {@value #SCATTER_COUNT} writes into a {@code DynamicChunk}. + */ + @Benchmark + public void minestomSetBlock() { + writeScatter(this.minestomChunk); + } + + /** + * Measures a scattered batch of {@value #SCATTER_COUNT} writes into a {@code FalcoChunk}. + */ + @Benchmark + public void falcoSetBlock() { + writeScatter(this.falcoChunk); + } + + /** + * Measures a scattered batch of {@value #SCATTER_COUNT} reads from a {@code DynamicChunk}. + * + * @return the sum of the read state ids + */ + @Benchmark + public int minestomGetBlock() { + return readScatter(this.minestomChunk); + } + + /** + * Measures a scattered batch of {@value #SCATTER_COUNT} reads from a {@code FalcoChunk}. + * + * @return the sum of the read state ids + */ + @Benchmark + public int falcoGetBlock() { + return readScatter(this.falcoChunk); + } + + /** + * Measures a full copy of a {@code DynamicChunk}. + * + *

This arm is not comparable to {@link #falcoCopy()} and its number must not be quoted

+ *

+ * A copy constructs a chunk, and constructing a chunk for an {@code InstanceContainer} leaves an + * entry in the viewer cache of its entity tracker that nothing removes. The cache is keyed by a + * record whose {@code equals} compares the shared instance list by identity, and + * {@code InstanceContainer#getSharedInstances} hands out a fresh {@code unmodifiableList} every + * time, so no key ever matches one already there. Every invocation of this method therefore + * inserts, and because that record leaves the value based {@code hashCode} in force while no two + * keys compare equal, the insertions pile into a single bin. + *

+ *

+ * What this method reports is consequently the cost of a copy plus the cost of a hash map that + * grows for the length of the trial. {@link #falcoCopy()} does not pay it, for the sole reason + * that a {@code FalcoInstance} is not an {@code InstanceContainer} and is handed the + * {@code List.of()} singleton instead, whose identity is stable. The two implementations differ + * only in that the Falco one additionally carries over its tickable counter, one {@code int} + * assignment, so on the code alone this arm should be the faster of the two, not slower by more + * than an order of magnitude. + *

+ *

+ * {@code ChunkViewerCacheLeakTest} establishes the mechanism and its linearity. + * {@link #minestomCopyIsolated()} is the arm that separates the copy from the leak, and it and + * {@link #falcoCopyIsolated()} are the only pair here whose ratio means anything. + *

+ * + *

Why this arm is kept out of the baseline run

+ *

+ * The time this arm reports is not a value but a slope, and the scouting run of 2026-08-01 shows + * it directly. Its three measurement iterations read {@code 296}, {@code 313} and + * {@code 364 us/op} at {@code distinctStates = 64} and {@code 282}, {@code 304} and + * {@code 390 us/op} at {@code 1024} — rises of {@code 23 %} and {@code 38 %} within one fork — + * while every control arm on the same fork was flat to within two percent + * ({@link #falcoSetBlock()} at {@code 1024}: {@code 106,86}, {@code 107,19}, {@code 106,64}). + * The map is still growing while the mean is being taken, so the mean depends on how long the + * iteration ran and a different {@code -i} produces a different answer. The same run shows the + * arm is not measuring a copy at all: its mean barely moves across the state count + * ({@code 363}, {@code 325}, {@code 325 us/op}) where {@link #falcoCopy()} scales with the + * content it copies ({@code 7,8}, {@code 16,2}, {@code 22,1 us/op}). + *

+ *

+ * The allocation column of this arm is a different matter and is worth publishing. This arm + * minus {@link #falcoCopy()} in {@code gc.alloc.rate.norm} was {@code 257,1}, {@code 257,3} and + * {@code 257,3 B/op} at the three measured state counts, at an error below {@code 0,6 B}: the + * per copy cost of the leak, constant in what the chunk holds. {@code docs/benchmarks/full-run.sh} + * therefore runs this arm and {@link #falcoCopy()} only under {@code --with-leak-arms}, into a + * separate file whose name records that its time column is not a baseline. + *

+ * + * @return the created copy + */ + @Benchmark + public Chunk minestomCopy() { + return copy(this.minestomChunk, this.container); + } + + /** + * Measures a full copy of a {@code FalcoChunk}. + *

+ * Read the note on {@link #minestomCopy()} before comparing the two. This arm is the one that is + * free of the viewer cache leak, which makes the pair incomparable rather than making this side + * fast. Taken on its own the number is sound; taken as a ratio it is not. + *

+ * + * @return the created copy + */ + @Benchmark + public Chunk falcoCopy() { + return copy(this.falcoChunk, this.falco); + } + + /** + * Measures a full copy of a {@code DynamicChunk} into an instance that is not a container. + * + *

Why the destination is the Falco instance

+ *

+ * {@link #minestomCopy()} and {@link #falcoCopy()} cannot be divided by one another, because the + * first pays for a viewer cache entry that leaks on every chunk construction and the second does + * not. The leak is a property of the destination instance rather than of the chunk being copied: + * a chunk asks the entity tracker of the instance it is being built for, and only an + * {@code InstanceContainer} hands that tracker a list whose identity changes each time. + *

+ *

+ * {@code Chunk#copy(Instance, int, int)} takes the destination as a parameter, so both + * implementations can be pointed at the same instance that is not a container. Both then pay the + * same cache cost, which is one lookup that hits, and what remains between them is the work the + * two implementations actually do. That is what this arm and {@link #falcoCopyIsolated()} + * measure, and they are the only pair of copy arms in this class whose ratio means anything. + *

+ *

+ * The isolation costs realism and says so: a server copies a chunk within its own world, and if + * that world is an {@code InstanceContainer} it really does pay what {@link #minestomCopy()} + * reports. The pair is kept for that reason. This arm answers what a copy costs, the other one + * answers what it costs today. + *

+ * + * @return the created copy + */ + @Benchmark + public Chunk minestomCopyIsolated() { + return copy(this.minestomChunk, this.falco); + } + + /** + * Measures a full copy of a {@code FalcoChunk} into an instance that is not a container. + *

+ * The counterpart of {@link #minestomCopyIsolated()}, against which it is comparable. On the + * code alone this arm is expected to be the slower of the two by a margin too small to resolve, + * because {@code FalcoChunk#copy} additionally carries over its tickable counter — one + * {@code int} assignment — while {@code DynamicChunk#copy} copies only {@code entries}. Until + * this task the extra work was a whole {@code Int2ObjectOpenHashMap} copy, which is why this + * paragraph used to expect a small but real margin rather than none. A result in the other + * direction by more than noise means this pair is measuring something other than the copy as + * well. + *

+ * + * @return the created copy + */ + @Benchmark + public Chunk falcoCopyIsolated() { + return copy(this.falcoChunk, this.falco); + } + + /** + * Measures a full heightmap refresh of a {@code DynamicChunk}. + * + * @return the sum of the refreshed heights of both heightmaps + */ + @Benchmark + public int minestomHeightmapRefresh() { + return refreshHeightmaps(this.minestomChunk); + } + + /** + * Measures a full heightmap refresh of a {@code FalcoChunk}. + * + * @return the sum of the refreshed heights of both heightmaps + */ + @Benchmark + public int falcoHeightmapRefresh() { + return refreshHeightmaps(this.falcoChunk); + } + + /** + * Writes the scatter batch into a chunk. + *

+ * The write lock is taken once around the whole batch rather than once per block, which is what + * {@code InstanceContainer#UNSAFE_setBlock} does. That is deliberate: an uncontended + * {@code ReentrantReadWriteLock} acquisition is a compare and swap on a field every write of + * the batch would touch again, and taking it {@value #SCATTER_COUNT} times would fold a lock + * measurement into a storage measurement. The lock model is the subject of its own benchmark, + * B-16, where it is the thing being varied instead of a constant overhead on both arms. + *

+ *

+ * The method is shared by both arms on purpose. It is the same code, the same loop and the same + * call site for {@code DynamicChunk} and for {@code FalcoChunk}, so a difference between the + * two arms cannot come from the way they are driven. Each benchmark method also runs in its own + * fork, so the call site sees exactly one receiver type per measurement and neither arm pays + * for the existence of the other. + *

+ * + * @param chunk the chunk to write into + */ + private void writeScatter(Chunk chunk) { + chunk.lockWriteLock(); + try { + for (int index = 0; index < SCATTER_COUNT; index++) { + chunk.setBlock(this.scatterX[index], this.scatterY[index], this.scatterZ[index], + this.scatterBlocks[index]); + } + } finally { + chunk.unlockWriteLock(); + } + } + + /** + * Reads the scatter batch from a chunk and sums the state ids it finds. + *

+ * The read runs with {@code Block.Getter.Condition#NONE}, which is the condition + * {@code Instance#getBlock} uses and therefore the one production reaches. It is also the more + * expensive of the two: {@code CONDITION#TYPE} answers from the palette alone, while + * {@code NONE} first consults the block entity map. That map is empty here, because the fixture + * excludes block entities from every fill, so what the condition really measures is the guard + * in front of the map — which is exactly the branch a real chunk of plain terrain takes on + * every read. + *

+ *

+ * The sum exists to keep the reads alive. Without a consumed result the whole loop is dead code + * and a compiler is free to delete it, which would turn the arm into a measurement of an empty + * loop and would do so silently. + *

+ * + * @param chunk the chunk to read from + * @return the sum of the read state ids + */ + private int readScatter(Chunk chunk) { + int sum = 0; + + chunk.lockReadLock(); + try { + for (int index = 0; index < SCATTER_COUNT; index++) { + final Block block = chunk.getBlock(this.scatterX[index], this.scatterY[index], + this.scatterZ[index], Block.Getter.Condition.NONE); + sum += Objects.requireNonNullElse(block, Block.AIR).stateId(); + } + } finally { + chunk.unlockReadLock(); + } + return sum; + } + + /** + * Copies a chunk to a neighbouring position of the same instance. + *

+ * The copy is placed at a position the instance does not hold and is never registered, so it + * becomes garbage as soon as the blackhole has consumed it. That is the intent: this arm is + * measured for its allocation as much as for its time, and a copy that stayed reachable would + * fill the heap of the fork within seconds instead. + *

+ *

+ * The read lock is required rather than optional. Both {@code DynamicChunk#copy} and + * {@code FalcoChunk#copy} open with {@code assertReadLock()}, so a run with assertions enabled + * would fail here without it. + *

+ * + * @param chunk the chunk to copy + * @param instance the instance the copy is created for + * @return the created copy + */ + private Chunk copy(Chunk chunk, Instance instance) { + chunk.lockReadLock(); + try { + return chunk.copy(instance, CHUNK_POSITION + 1, CHUNK_POSITION); + } finally { + chunk.unlockReadLock(); + } + } + + /** + * Recomputes both heightmaps of a chunk from scratch and sums the heights that come out. + *

+ * This is the body of the private {@code calculateFullHeightmap} of whichever chunk it is + * handed, reproduced through public API. The method itself cannot be called from outside the + * chunk, and the public + * {@code Heightmap#refresh(int)} that it uses returns immediately once a heightmap has been + * refreshed, with no public way to arm it again. {@code Heightmap#refresh(int, int, int)} is + * the same scan per column without that guard, so driving it over all {@code 256} columns + * performs the identical work and performs it on every invocation instead of only on the first. + *

+ *

+ * Both heightmaps are refreshed because both of them are refreshed by the code being modelled, + * and because they differ in their predicate rather than in their scan: one counts every block + * that blocks motion, the other every block that is not air. Measuring only one of them would + * halve a cost that a real chunk always pays twice. + *

+ *

+ * The write lock is the lock {@code calculateFullHeightmap} asserts, so it is the lock taken + * here, even though the scan itself only reads the palettes and writes into the height array of + * the heightmap. Modelling the real path matters more than taking the cheaper lock, and it + * costs a single uncontended acquisition per invocation against a scan of {@code 256} columns. + *

+ *

+ * The starting height is recomputed on every invocation rather than cached, because + * {@code calculateFullHeightmap} recomputes it too. It walks the sections from the top until it + * meets one with a block in it, which on a filled chunk stops at the first section. + *

+ *

+ * Each arm computes that height the way its own chunk computes it, which is the one place where + * this helper deliberately does not run the same code on both sides. + * {@code DynamicChunk#calculateFullHeightmap} calls + * {@code Heightmap#getHighestBlockSection(Chunk)}, which walks the chunk through + * {@code Chunk#getSection(int)}; {@code FalcoChunk#calculateFullHeightmap} calls + * {@link FalcoChunk#highestBlockSection()}, which walks its storage through a view and creates + * nothing. Driving both arms through the static helper would be the same code but the wrong + * model — it would charge the Falco arm a scan its chunk does not perform, on sections its chunk + * does not create. The two return the same number on two chunks holding the same blocks, which + * is asserted rather than assumed in {@code FalcoChunkEquivalenceTest}, and a disagreement + * surfaces here as a differing sum and aborts the trial. + *

+ * + * @param chunk the chunk to refresh the heightmaps of + * @return the sum of the refreshed heights of both heightmaps + */ + private static int refreshHeightmaps(Chunk chunk) { + int sum = 0; + + chunk.lockWriteLock(); + try { + final int startY = chunk instanceof FalcoChunk falcoChunk + ? falcoChunk.highestBlockSection() + : Heightmap.getHighestBlockSection(chunk); + final Heightmap motionBlocking = chunk.motionBlockingHeightmap(); + final Heightmap worldSurface = chunk.worldSurfaceHeightmap(); + + for (int x = 0; x < Chunk.CHUNK_SIZE_X; x++) { + for (int z = 0; z < Chunk.CHUNK_SIZE_Z; z++) { + motionBlocking.refresh(x, z, startY); + worldSurface.refresh(x, z, startY); + } + } + for (int x = 0; x < Chunk.CHUNK_SIZE_X; x++) { + for (int z = 0; z < Chunk.CHUNK_SIZE_Z; z++) { + sum += motionBlocking.getHeight(x, z) + worldSurface.getHeight(x, z); + } + } + } finally { + chunk.unlockWriteLock(); + } + return sum; + } + + /** + * Draws the positions and the blocks of the scatter batch. + *

+ * The positions are distinct. A batch that could hit a position twice would measure a + * guaranteed cache hit on the repetition, which is the opposite of what a scattered access + * pattern is for, and its second write would delete the block its first write placed — which + * would break the guarantee that every state of the set survives the batch and would take the + * exact state count check of {@link #verifyStateCount()} with it. Duplicates are therefore + * rejected through a bit set over the block index rather than tolerated. + *

+ *

+ * The blocks cycle through the same set the fill drew from, so a batch cannot introduce a state + * that the {@code distinctStates} axis did not ask for. The seed is the one of the module, so + * the same parameter combination produces the same batch on every run and on every machine. + *

+ */ + private void buildScatter() { + final int minY = this.minestomChunk.getMinSection() * Chunk.CHUNK_SECTION_SIZE; + final int height = (this.minestomChunk.getMaxSection() - this.minestomChunk.getMinSection()) + * Chunk.CHUNK_SECTION_SIZE; + final Block[] blocks = MinestomChunks.distinctBlocks(this.distinctStates); + final Random random = new Random(BenchmarkConstants.SEED); + final BitSet taken = new BitSet(Chunk.CHUNK_SIZE_X * Chunk.CHUNK_SIZE_Z * height); + + this.scatterX = new int[SCATTER_COUNT]; + this.scatterY = new int[SCATTER_COUNT]; + this.scatterZ = new int[SCATTER_COUNT]; + this.scatterBlocks = new Block[SCATTER_COUNT]; + + for (int index = 0; index < SCATTER_COUNT; index++) { + int x; + int y; + int z; + int packed; + + do { + x = random.nextInt(Chunk.CHUNK_SIZE_X); + y = random.nextInt(height); + z = random.nextInt(Chunk.CHUNK_SIZE_Z); + packed = (y * Chunk.CHUNK_SIZE_Z + z) * Chunk.CHUNK_SIZE_X + x; + } while (taken.get(packed)); + + taken.set(packed); + this.scatterX[index] = x; + this.scatterY[index] = minY + y; + this.scatterZ[index] = z; + this.scatterBlocks[index] = blocks[index % blocks.length]; + } + } + + /** + * Verifies that the two instances handed out the two chunk types this benchmark compares. + *

+ * Both chunks come from the default chunk supplier of their instance, which is the subject of + * the comparison rather than a setting of it. A supplier that changed on either side — in + * Minestom, in {@code FalcoInstance} or in the fixture — would leave every other assertion of + * this class intact while the benchmark quietly measured one type against itself and reported + * two arms that agree perfectly. That is the one failure this benchmark could not survive + * undetected, because agreement is exactly the result it expects. + *

+ *

+ * The Minestom arm used to carry a second clause, {@code || minestomChunk instanceof FalcoChunk}, + * and it was load bearing while {@code FalcoChunk} extended {@code DynamicChunk}: a Falco chunk + * passed the first check back then. Since stage 1 of the block storage work the two are + * siblings under {@code Chunk}, so no object can satisfy both tests and the clause could never + * fire again. It is gone rather than kept as insurance, because a check that cannot fail reads + * like a check that does. + *

+ * + * @throws IllegalStateException if either chunk is not of the type its arm claims to measure + */ + private void verifyArms() { + if (!(this.minestomChunk instanceof DynamicChunk)) { + throw new IllegalStateException("The Minestom arm has to measure a plain DynamicChunk but the" + + " container handed out a " + this.minestomChunk.getClass().getName()); + } + if (!(this.falcoChunk instanceof FalcoChunk)) { + throw new IllegalStateException("The Falco arm has to measure a FalcoChunk but the instance" + + " handed out a " + this.falcoChunk.getClass().getName()); + } + } + + /** + * Verifies that both chunks hold exactly as many distinct block states as the axis asked for. + *

+ * The second half of the anti tautology check. {@code assertNotAllAir} only rules out the + * empty chunk; this rules out the chunk that took the fill but not the parameter. A trial that + * ran at {@code distinctStates == 1024} while its chunk held sixteen would produce a perfectly + * plausible number for a point of the curve that was never built, and no walk over the blocks + * would notice, because both sides would hold the same wrong content. + *

+ *

+ * The comparison is exact rather than a lower bound, which the scatter batch is what makes + * possible: it writes every block of the set into a distinct position, so every shape reaches + * the full count. The fixture counts air as a state, and the fills of this module write to + * every position of the chunk, so no air is left to inflate the count. + *

+ * + * @throws IllegalStateException if a chunk holds a different amount of distinct states than + * requested, or if the two chunks disagree + */ + private void verifyStateCount() { + final int minestomStates = MinestomChunks.countDistinctStates(this.minestomChunk); + final int falcoStates = MinestomChunks.countDistinctStates(this.falcoChunk); + + if (minestomStates != falcoStates) { + throw new IllegalStateException("The chunks hold a different amount of distinct states:" + + " DynamicChunk " + minestomStates + " against FalcoChunk " + falcoStates); + } + if (minestomStates != this.distinctStates) { + throw new IllegalStateException("The measured chunks hold " + minestomStates + + " distinct block states but the axis asked for " + this.distinctStates + + " under the shape " + this.fillShape + ", so the run would report a point of the" + + " curve it never built"); + } + } +} diff --git a/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/ChunkLookupBenchmark.java b/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/ChunkLookupBenchmark.java new file mode 100644 index 0000000..2b254e0 --- /dev/null +++ b/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/ChunkLookupBenchmark.java @@ -0,0 +1,163 @@ +package net.onelitefeather.falco.benchmark.instance; + +import net.minestom.server.coordinate.CoordConversion; +import org.openjdk.jmh.annotations.Benchmark; +import org.openjdk.jmh.annotations.BenchmarkMode; +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.infra.Blackhole; +import space.vectrix.flare.fastutil.Long2ObjectSyncMap; + +import java.util.Map; +import java.util.concurrent.ConcurrentHashMap; +import java.util.concurrent.TimeUnit; + +/** + * Prices the boxed chunk index against the unboxed one, on the lookup and on the write. + *

+ * US-3.05 asks for the boxing to go and the design refuses to sell that as a speed change, because + * the cost of the boxing is not established. This benchmark is what would establish it, and it + * measures both directions on purpose: the lookup, which is what the change is for, and the write, + * which is where {@code Long2ObjectSyncMap} is expected to be the more expensive of the two, + * since a write after a run of misses rebuilds its dirty map. A change that reports only the side it + * improves is not a measurement. + *

+ *

+ * That expectation is stated here rather than asserted, because the first run did not meet it: the + * primitive arm was the cheaper one on the write side too, in time and in allocation, at all three + * sizes. Read that as "this benchmark did not provoke a promotion", not as "the promotion is free" — + * every operation of the write arms puts and removes the same single key, which is the cheapest shape + * a dirty map can be asked for. The figures are in the {@code Stage 3 result} section of + * {@code docs/superpowers/plans/2026-08-02-falco-instance-facade.md}, together with the note that + * their timings come from a scouting configuration on a loaded machine and may not be quoted. + *

+ *

+ * Both maps are driven with the same key sequence and the same content. Neither arm touches a real + * chunk — the value is a plain {@code Object} standing in for one — because the question is about the + * map and a chunk would put a two hundred kilobyte object into a cache line argument. + *

+ * + *

Why the boxed lookup arm allocates far more than a box

+ *

+ * The keys are a square grid of chunk positions and {@code Long#hashCode} of a chunk index is + * {@code chunkX ^ chunkZ}, so from a side of about ten upwards the whole grid falls into a handful of + * buckets and the bins of the boxed map treeify. A treeified bin reaches + * {@code HashMap#comparableClassFor}, which calls {@code Class#getGenericInterfaces} on every lookup + * and allocates reflectively. Measured outside JMH with a per-thread counter: 24 B of the boxed arm + * are the box and about 46 B are this, the second figure appearing with a pre-boxed key as well and + * disappearing when the keys are spread or the grid stays under the treeify threshold. + *

+ *

+ * The effect belongs to real chunk coordinates and not to this key generator, which is why it is kept + * rather than designed away — but it means the allocation column of the boxed arm must not be read as + * "this is what boxing costs". + *

+ * + * @author TheMeinerLP + * @version 1.1.0 + * @since 0.4.0 + */ +@State(Scope.Benchmark) +@BenchmarkMode(Mode.AverageTime) +@OutputTimeUnit(TimeUnit.NANOSECONDS) +public class ChunkLookupBenchmark { + + /** + * How many chunk positions the maps hold, which is roughly a view distance of eight, sixteen and + * a streaming world. + */ + @Param({"289", "1089", "4096"}) + public int positions; + + /** + * The value every key maps to. + */ + private final Object value = new Object(); + + /** + * The boxed map, the shape this stage replaced. + */ + private Map boxed; + + /** + * The primitive map, the shape this stage installed. + */ + private Long2ObjectSyncMap primitive; + + /** + * The keys, in the order the benchmark walks them. + */ + private long[] keys; + + /** + * Creates the state object, which JMH fills through {@link #setUp()}. + */ + public ChunkLookupBenchmark() { + } + + /** + * Fills both maps with the same content. + */ + @Setup + public void setUp() { + this.boxed = new ConcurrentHashMap<>(); + this.primitive = Long2ObjectSyncMap.hashmap(); + this.keys = new long[this.positions]; + + final int side = (int) Math.ceil(Math.sqrt(this.positions)); + for (int index = 0; index < this.positions; index++) { + final long key = CoordConversion.chunkIndex(index % side, index / side); + this.keys[index] = key; + this.boxed.put(key, this.value); + this.primitive.put(key, this.value); + } + } + + /** + * Walks every position through the boxed map. + * + * @param blackhole where the results go + */ + @Benchmark + public void boxedLookup(Blackhole blackhole) { + for (long key : this.keys) blackhole.consume(this.boxed.get(key)); + } + + /** + * Walks every position through the primitive map. + * + * @param blackhole where the results go + */ + @Benchmark + public void primitiveLookup(Blackhole blackhole) { + for (long key : this.keys) blackhole.consume(this.primitive.get(key)); + } + + /** + * Puts and removes one position in the boxed map, which is what a load and an unload do. + * + * @param blackhole where the results go + */ + @Benchmark + public void boxedLoadAndUnload(Blackhole blackhole) { + final long key = CoordConversion.chunkIndex(9999, 9999); + blackhole.consume(this.boxed.put(key, this.value)); + blackhole.consume(this.boxed.remove(key)); + } + + /** + * Puts and removes one position in the primitive map. + * + * @param blackhole where the results go + */ + @Benchmark + public void primitiveLoadAndUnload(Blackhole blackhole) { + final long key = CoordConversion.chunkIndex(9999, 9999); + blackhole.consume(this.primitive.put(key, this.value)); + blackhole.consume(this.primitive.remove(key)); + } +} diff --git a/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/ChunkResendCostBenchmark.java b/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/ChunkResendCostBenchmark.java new file mode 100644 index 0000000..bd18833 --- /dev/null +++ b/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/ChunkResendCostBenchmark.java @@ -0,0 +1,962 @@ +package net.onelitefeather.falco.benchmark.instance; + +import net.minestom.server.MinecraftServer; +import net.minestom.server.ServerFlag; +import net.minestom.server.ServerProcess; +import net.minestom.server.coordinate.ChunkRange; +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.InstanceContainer; +import net.minestom.server.instance.Section; +import net.minestom.server.instance.block.Block; +import net.minestom.server.network.ConnectionState; +import net.minestom.server.network.NetworkBuffer; +import net.minestom.server.network.packet.PacketWriting; +import net.minestom.server.network.packet.server.SendablePacket; +import net.minestom.server.network.packet.server.ServerPacket; +import net.minestom.server.network.packet.server.play.ChunkDataPacket; +import net.onelitefeather.falco.benchmark.support.BenchmarkConstants; +import net.onelitefeather.falco.benchmark.support.MinestomChunks; +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.TearDown; +import org.openjdk.jmh.annotations.Warmup; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; +import java.util.concurrent.TimeUnit; + +/** + * The {@link ChunkResendCostBenchmark} class measures what a full chunk resend at view distance + * {@code 10} actually costs, in time, in bytes on the wire and in allocated heap, so that the + * SharedInstance question of Falco is decided on a number rather than on an intuition. + * + *

The decision this benchmark serves

+ *

+ * When a player changes instance, {@code Player#setInstance} asks + * {@code SharedInstance.areLinked(currentInstance, instance)} first (Player.java:618 of the pinned + * build). If the two instances share their block storage and the player stays in the same chunk, the + * player is respawned into the new instance without a single chunk packet: the client already holds + * the correct version of every chunk around it. Everything else falls through to the slow path, + * which queues every chunk in range and sends {@code chunk.getFullDataPacket()} for each of them + * (Player.java:794). + *

+ *

+ * That fast path is reachable only through Minestom's own types. {@code areLinked} decides by + * {@code instanceof SharedInstance} and {@code instanceof InstanceContainer} + * (SharedInstance.java:141-153), and {@code SharedInstance} stores its owner in a field typed to the + * concrete {@code InstanceContainer} (SharedInstance.java:22). An architecture in which Falco keeps + * its own block store, held by two instances side by side instead of one instance pointing at + * another, is the cleaner shape and dissolves the aliasing defects of {@code SharedInstance} — but + * it is not an {@code InstanceContainer}, so {@code areLinked} returns {@code false} and the fast + * path is gone. The clean design therefore has an exact price: one full resend per instance change. + * This class puts a number on it. + *

+ * + *

Why the result is an absolute price and not a ratio

+ *

+ * There is no second arm to compare against. The fast path does not send a cheaper packet, it sends + * no packet at all, so its cost is zero by construction and any ratio against it would be infinite. + * Every number this class produces is therefore the whole bill of giving the fast path up, and the + * decision rule is an absolute threshold rather than a factor: a resend that costs a fraction of a + * tick and a few hundred kilobytes is a price worth paying for a sound architecture, and one that + * costs several ticks and tens of megabytes per instance change is not. + *

+ * + *

The unit is a column of 441 chunks, not one chunk

+ *

+ * {@code ChunkRange.chunksCount(10)} is {@code 441}, and that is the number of packets the slow path + * builds for a single player. {@link #resendViewDistance10()} therefore walks {@code 441} distinct + * chunks per operation rather than one chunk {@code 441} times. The distinction is not pedantry: a + * single chunk stays in cache across iterations and would report the cost of a resend that never + * leaves L2, while a real column of terrain is tens of megabytes of palette storage that the + * serializer has to stream through memory once per resend. + *

+ *

+ * The {@code 441} chunks are built with {@link Chunk#copy(net.minestom.server.instance.Instance, int, int)} + * from one filled source chunk, over the same spiral of coordinates + * {@code ChunkRange.chunksInRange} hands to the player, and they are deliberately identical in + * content. Copying clones every {@code Section}, so each chunk owns its palettes, its light arrays + * and its packet cache, which is what the memory traffic of the measurement depends on. Identical + * content is what keeps the content axis an axis: two runs at the same parameter must differ in + * nothing but the code under measurement, and terrain that varied per chunk would turn the byte + * volume into a property of the generator instead of a property of the parameter. + *

+ *

+ * The single chunk methods next to it exist so that the column figure can be checked against its own + * parts. {@link #buildAndSerializeOneChunkPacket()} times {@code 441} times over should come close to + * {@link #resendViewDistance10()}; the gap between the two is the memory locality penalty of walking + * a whole column, and it is the one part of the answer that a per chunk measurement structurally + * cannot show. + *

+ * + *

What one packet actually holds

+ *

+ * {@code DynamicChunk#createChunkPacket} (DynamicChunk.java:256) builds a {@code ChunkDataPacket} + * out of four pieces: both heightmaps, which the first call computes and every later call reads back + * from memoised state; the light data of all {@code 24} sections; the block palettes of all + * {@code 24} sections, serialised into one {@code byte[]} through {@code NetworkBuffer.makeArray}; + * and the block entity map. Three of the four allocation posts the research report names sit in that + * path — {@code data.clone()} in the {@code ChunkData} constructor (ChunkData.java:26), the boxing + * of every block entity key through {@code Map.Entry::getKey} into an unmodifiable map + * (ChunkData.java:27-30), and the doubling of the {@code NetworkBuffer} that starts at {@code 256} + * bytes (NetworkBuffer.java:328-332). + *

+ * + *

Why the packet cache is switched off

+ *

+ * {@code DynamicChunk#getFullDataPacket} does not return a packet, it returns the {@code CachedPacket} + * that wraps {@code createChunkPacket} (DynamicChunk.java:58 and :230). That cache keeps its result + * in a {@code SoftReference} and, when {@code ServerFlag.CACHED_PACKET} is on, does the framing and + * the compression inside the same call. Two things follow that a measurement cannot live with: a + * soft reference may be cleared by the garbage collector in the middle of an iteration, which turns + * a cache hit into a full rebuild at a moment nobody controls, and the build cannot be told apart + * from the framing because both happen behind one method. + *

+ *

+ * The fork therefore runs with {@code -Dminestom.cached-packet=false}, and {@link #setUp()} refuses + * to measure if that flag did not arrive. With the cache off, + * {@code SendablePacket.extractServerPacket} resolves straight to {@code createChunkPacket}, so + * {@link #buildOneChunkPacket()} times the build alone, {@link #serializeOneChunkPacket()} times the + * framing alone on a packet built once in the setup, and + * {@link #buildAndSerializeOneChunkPacket()} times the sum — which is exactly what the enabled cache + * would have done in one step. + *

+ *

+ * What that flag costs the benchmark is stated rather than hidden: on a live server with the cache + * enabled, the second and every further player to receive the same chunk pays neither the build nor + * the framing, only the write of an already framed buffer into its own connection. This class cannot + * time that write, because it needs a real {@code PlayerConnection}, and it does not pretend to. It + * bounds it instead: that write moves exactly the amount of bytes this class reports, and nothing + * more. The build and framing numbers are the price of the first resend of a chunk and of every + * resend whose cache entry was invalidated by a block change or dropped by the collector. + *

+ * + *

The bytes are the compressed bytes

+ *

+ * {@code PacketWriting.allocateTrimmedPacket} is the method the connection layer itself uses, and + * with a compression threshold above zero — Minestom defaults to {@code 256} — it deflates every + * chunk packet before the length prefixes are written. The reported wire size is therefore the size + * after compression, which is the number that actually travels, and it is far below the serialised + * size for exactly the contents where it matters most: a fully lit air chunk ships {@code 24} arrays + * of {@code 2048} identical bytes and deflates to almost nothing. Both figures are reported side by + * side in the setup line, because the uncompressed one is what the serializer had to produce and the + * compressed one is what the socket had to carry. + *

+ * + *

The content axis, and the light that comes with it

+ *

+ * A chunk packet is not one thing, and a single number for "a chunk" would be a number for whichever + * content the author happened to build. The four values bracket the range rather than sample it, and + * they are chosen so that no two of them are extreme in the same quantity: the content with the + * largest serialised payload is not the content with the largest wire size, because compression + * reorders the ranking. A reader who takes only one row out of this table has to take the row that + * matches the world the decision is about. + *

+ *

+ * Sky light is part of the content rather than a second axis, and it is seeded to what the content + * physically implies: an air chunk is lit through, a chunk of solid stone to the build limit is dark + * everywhere, and a chunk with a surface at {@code y=64} is lit above it and dark below. Seeding + * happens through {@code Section#setSkyLight}, so no light engine runs during the measurement — the + * model is a server whose chunks are loaded and already lit, which is the state a player finds when + * it changes instance. A dark section contributes no bytes at all, because + * {@code DynamicChunk#createLightData} only sends arrays whose length is not zero + * (DynamicChunk.java:303-315), which is why the block light of every content here is empty: the + * fixture places no light emitting blocks. + *

+ *

+ * The consequence is that {@link ChunkContent#EMPTY} is not the free case it looks like. An air + * chunk carries no palette data worth mentioning and up to {@code 24 x 2048} bytes of sky light, + * and that asymmetry is a result rather than a nuisance: a lobby of empty instances pays for its + * resends too. + *

+ * + *

What the allocation profiler sees and what it misses

+ *

+ * {@code -prof gc} reports {@code gc.alloc.rate.norm}, which counts heap allocation per operation. + * It covers the {@code data.clone()} of {@code ChunkData}, the maps and lists the block entity + * filter and the light data build, and the {@code byte[]} that {@code makeArray} finally reads out. + * It does not cover the growth of the {@code NetworkBuffer} itself: every doubling step is + * an {@code Arena.ofAuto().allocate} (NetworkBufferImpl.java:203 and :243), which is native memory + * released by the collector rather than heap, and a native segment does not appear in an allocation + * rate. The third of the three posts named in the report is therefore visible in this benchmark only + * through the time it takes, not through the bytes it moves, and a reader who subtracts the reported + * allocation from the packet size will find a gap that is exactly that. + *

+ * + *

The equivalence stage

+ *

+ * The premise of the whole question is that a resend delivers data the client already has. If a + * rebuilt packet were not byte for byte the packet that was sent before, the resend would not be + * redundant work but necessary work, and measuring "the price of avoidable traffic" would be + * measuring the wrong thing entirely. {@link #setUp()} therefore rebuilds and reserialises the same + * chunk twice and compares the two byte sequences before a single measurement is taken, in the shape + * {@code LightEngineComparisonBenchmark#verifyBothEnginesAgree} established for this module: it + * throws, and the trial stops instead of publishing a number. + *

+ *

+ * Three further checks guard the fixture itself. Every chunk of the column has to serialise to the + * same uncompressed length, which is what makes the column homogeneous enough for a per chunk + * average to mean anything; the compressed lengths are only summed and their spread reported, since + * the chunk coordinates differ and deflate is free to answer a different length for a different + * input. A sample of the copies is compared against the source through + * {@code MinestomChunks#assertSameBlocks}, block by block and heightmap by heightmap, because a copy + * that silently lost its content would make every packet of the column smaller than the parameter + * claims. And the count of lit sections is verified against what the content promises, because sky + * light is the largest single contributor to the byte volume and a fixture that lost it would report + * a resend that costs a fraction of the real one. + *

+ * + *

What this benchmark does not answer

+ *

+ * It measures the server side of one resend and nothing else. The client side cost of ingesting + * {@code 441} chunks, the bandwidth of the link, the entity and viewer bookkeeping that + * {@code Player#spawnPlayer} performs alongside the chunks, and the chunk rate limiter that spreads + * the batch over several ticks + * ({@code ServerFlag.MAX_CHUNKS_PER_TICK}, Player.java:780-781) are all outside it. The rate limiter + * in particular means that the wall clock latency a player perceives is governed by the tick budget + * rather than by the numbers here; what the numbers here decide is how much of the tick budget the + * resend consumes, which is the part Falco controls. + *

+ * + *

Running it

+ *

+ * The full cross product is four scenarios per method. The resend method moves the whole column per + * operation and is the slow one; the three single chunk methods are cheap and can be run on their + * own while iterating on the packet path. + *

+ * 
{@code
+ * ./gradlew :falco-benchmarks:jmh -Pjmh.include=ChunkResendCostBenchmark
+ *
+ * java -jar build/libs/falco-*-jmh.jar "ChunkResendCostBenchmark" -prof gc -f 1 -wi 5 -i 5
+ * java -jar build/libs/falco-*-jmh.jar "ChunkResendCostBenchmark.resendViewDistance10" \
+ *     -prof gc -f 1 -wi 5 -i 5 -p content=EMPTY,TERRAIN
+ * }
+ *

+ * The Gradle task already sets the {@code gc} profiler for every benchmark of this module, and the + * {@code -Dminestom.cached-packet=false} the class depends on travels with the {@link Fork} + * annotation in both cases. Every trial prints one line naming the byte volume of its column before + * it starts, because that volume is a constant of the fixture rather than a measurement and JMH has + * no channel for a constant. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@State(Scope.Thread) +@BenchmarkMode(Mode.AverageTime) +@OutputTimeUnit(TimeUnit.MICROSECONDS) +@Fork(value = 1, jvmArgsAppend = {"-Xms2g", "-Xmx2g", "-Dminestom.cached-packet=false"}) +@Warmup(iterations = 5, time = 1) +@Measurement(iterations = 5, time = 1) +public class ChunkResendCostBenchmark { + + /** + * The view distance the resend is measured at, in chunks. + *

+ * Ten is the value the question was asked at and the value most servers run, above Minestom's own + * default of {@code 8} ({@code ServerFlag.CHUNK_VIEW_DISTANCE}) and below the client maximum. The + * cost scales with the square of it, so a server at {@code 8} pays roughly {@code 289 / 441} of + * what this class reports and one at {@code 16} roughly {@code 1089 / 441}. + *

+ */ + private static final int VIEW_DISTANCE = 10; + + /** + * The amount of chunk packets one resend produces, {@code 441} at {@link #VIEW_DISTANCE}. + * The value comes from {@code ChunkRange#chunksCount} rather than from a literal so that it stays + * the number the player path itself uses. + */ + private static final int RESEND_CHUNKS = ChunkRange.chunksCount(VIEW_DISTANCE); + + /** + * The block Y above which {@link ChunkContent#TERRAIN} is air. + *

+ * Sea level of the overworld, which puts the surface on a section boundary and therefore lets the + * sections above it be uniformly air and uniformly lit rather than half of each. A surface in the + * middle of a section would be more realistic in shape and would make the lit section count + * ambiguous, which is a bad trade for a fixture that has to verify that count. + *

+ */ + private static final int SURFACE_Y = 64; + + /** + * The length of the light array of one section, {@code 2048} bytes for {@code 4096} blocks at + * four bits each. + */ + private static final int LIGHT_ARRAY_LENGTH = BenchmarkConstants.BLOCK_ENTRIES / 2; + + /** + * The amount of distinct block states {@link ChunkContent#TERRAIN} draws from. + *

+ * Sixty-four states is what a generated overworld chunk holds in the same order of magnitude — + * stone, deepslate, dirt, gravel, the ores and their variants — and it puts every section palette + * into the indirect mode at six bits per entry, which is where a real chunk sits. Below that the + * palette collapses into a single value and stops being representative, above it the storage + * approaches the direct mode that {@link ChunkContent#DENSE} already covers. + *

+ */ + private static final int TERRAIN_STATES = 64; + + /** + * The amount of distinct block states {@link ChunkContent#DENSE} draws from. + *

+ * Two hundred and fifty-six states at one state per block is the ceiling of the axis: it fills + * eight bits per entry in every section, so the block data of the packet reaches {@code 4096} + * bytes per section, and the per block cycling leaves no run for the compressor to exploit. + *

+ */ + private static final int DENSE_STATES = 256; + + /** + * The amount of copies compared against the source chunk block by block. + *

+ * Three rather than all {@code 441}: the comparison walks {@code 98304} positions per pair, and + * the failure it guards against — a copy that lost its content — is a property of + * {@code Chunk#copy} rather than of an individual coordinate, so it shows on the first sample as + * readily as on the last. The samples are the first, the middle and the last of the column so + * that a failure of the loop that builds it is caught wherever it starts. + *

+ */ + private static final int COMPARED_COPIES = 3; + + /** + * The content the chunks of the measured column hold. + *

+ * Every value fixes the block states and the sky light together, because a chunk's light follows + * from its shape and a fixture that combined them freely would build worlds that cannot exist. + *

+ */ + public enum ChunkContent { + + /** + * Air everywhere, sky light in every section. + *

+ * The floor of the block data and, deliberately, not the floor of the packet: all + * {@code 24} sections are lit through, so the packet carries {@code 24 x 2048} bytes of sky + * light and nothing else worth naming. This is the shape of a void or lobby instance, and it + * is the case that decides whether a resend is cheap in the world where instance changes are + * most frequent. + *

+ */ + EMPTY, + + /** + * One block state in every position of the chunk, no light anywhere. + *

+ * The content that looks free and, by the hypothesis this value exists to test, is not. A + * chunk of solid stone to the build limit lets no sky light through, so it contributes no + * light bytes at all, and a palette that held a single value would need no backing array and + * would serialise to that one value. But the palette does not hold a single value by the time + * it is serialised: the very first write of a differing state grows it out of the + * single value form into the indirect form with a backing array + * ({@code PaletteImpl#initIndirect}), and nothing ever shrinks it back, because + * {@code PaletteImpl#optimize} has no call site anywhere in the Minestom main source tree. If + * that is right, every section of a uniform chunk still ships its full backing array, and + * this content is the cheapest way to see the wasted bytes without terrain on top of them. + *

+ *

+ * That makes it the control of the axis in both directions. Against {@link #EMPTY} it isolates + * what block data costs when there is only one block; against {@link #TERRAIN} it isolates + * what the variety of the terrain adds over a chunk that is merely full. + *

+ */ + UNIFORM, + + /** + * Runs of {@code 64} states below {@code y=64}, air and sky light above. + *

+ * The realistic case, and the one the decision should be read off. The ground is filled with + * {@code MinestomChunks.FillShape#RANDOM_RUNS}, whose autocorrelated runs are the property + * real terrain has and per block randomness destroys, and the sky above it is carved back to + * air and lit. That gives both halves of a real column: eight sections of terrain and sixteen + * sections of lit sky. + *

+ *

+ * The sixteen air sections are not free either, and for the same reason {@link #UNIFORM} + * exists. They were filled before they were carved, so their palettes grew a backing array + * and, with no call site for {@code PaletteImpl#optimize}, keep it after every entry in them + * has gone back to air. A chunk that a generator produced with air above the surface from the + * start would be cheaper than this one, which makes this content an upper bound on real + * terrain rather than a mean — and the size of that gap is itself a finding, since it is the + * price Minestom pays for never shrinking a palette. + *

+ */ + TERRAIN, + + /** + * {@code 256} states cycling per block through the whole chunk, no light anywhere. + *

+ * The ceiling of the serialised payload and of the work the serializer has to do. Two hundred + * and fifty-six distinct states force eight bits per entry in every section, which is the + * largest block data a chunk can carry short of the direct mode, and no world generator emits + * anything close to it. If the build and the serialisation are affordable here, they are + * affordable everywhere. + *

+ *

+ * It is deliberately not the ceiling on the wire, and the distinction is the reason + * the two byte figures are reported separately. A strict per block cycle is the most periodic + * input deflate can be handed, so the content that produces the largest buffer produces one of + * the smallest compressed frames. The realistic ceiling for the wire is {@link #TERRAIN}, + * whose runs are long enough to be cheap to store and irregular enough to resist compression. + *

+ */ + DENSE + } + + /** + * The content the chunks of this trial hold. + */ + @Param({"EMPTY", "UNIFORM", "TERRAIN", "DENSE"}) + public ChunkContent content; + + private ServerProcess process; + private InstanceContainer container; + private Chunk[] column; + private ChunkDataPacket prebuilt; + private int compressionThreshold; + + /** + * Builds the column of {@code 441} chunks the resend walks and proves that measuring + * it answers the question it was written for. + *

+ * The order matters. The content is written first, the sky light second, the copies third, and + * only then is one packet built and thrown away for every chunk of the column. That last pass is + * not a warm-up in the JMH sense: it pays the one-time costs a fresh chunk carries — the full + * heightmap refresh that {@code DynamicChunk#getHeightmaps} performs on its first call and never + * again — so that the measured operations see the state a loaded, lit and already served chunk is + * in. Without it the first operation of the first iteration would carry {@code 441} heightmap + * refreshes and the measurement would describe chunk generation instead of a resend. + *

+ * + * @throws IllegalStateException if the packet cache was not disabled, if a rebuilt packet differs + * from the packet built before it, if the chunks of the column + * disagree on their serialised length, if a copy lost the content + * of its source or if the sky light does not match the content + */ + @Setup(Level.Trial) + public void setUp() { + this.process = MinestomChunks.ensureServer(); + this.compressionThreshold = MinecraftServer.getCompressionThreshold(); + requireDisabledPacketCache(); + + this.container = MinestomChunks.newContainer(); + + final Chunk source = MinestomChunks.newChunk(this.container, 0, 0); + applyContent(source); + seedSkyLight(source); + + this.column = buildColumn(source); + for (Chunk chunk : this.column) { + serialize(buildPacket(chunk)); + } + this.prebuilt = asChunkDataPacket(buildPacket(this.column[0])); + + verifyRebuildIsIdentical(); + verifyColumnIsHomogeneous(); + verifyCopiesMatchSource(source); + verifySkyLightMatchesContent(); + + reportByteVolume(); + } + + /** + * Releases the instance and the column so that the next trial of the same fork starts on an empty + * heap. + *

+ * A column of {@code 441} chunks is tens of megabytes of palette storage, and four + * parameter values run in one fork. Leaving one trial's column reachable while the next one + * builds its own would put the measurement into a heap that is permanently near its limit and + * turn the answer into a statement about the garbage collector. + *

+ */ + @TearDown(Level.Trial) + public void tearDown() { + this.prebuilt = null; + this.column = null; + MinestomChunks.release(this.container); + this.container = null; + } + + /** + * Measures the build of one chunk packet, without serialising it. + *

+ * This is {@code DynamicChunk#createChunkPacket} and nothing else: the heightmaps read back from + * their memoised state, the light data assembled from the section arrays, the block palettes + * written into one growing {@code NetworkBuffer} and copied out of it, and the + * {@code ChunkData} constructor with its {@code data.clone()} and its block entity filter. + *

+ * + * @return the built packet + */ + @Benchmark + public ServerPacket buildOneChunkPacket() { + return buildPacket(this.column[0]); + } + + /** + * Measures the serialisation, framing and compression of one already built chunk packet. + *

+ * The packet is built once in the setup and reused, so this method holds still everything the + * build does and isolates what the connection layer adds on top: the walk over the packet through + * {@code ChunkDataPacket.SERIALIZER}, the deflate pass that + * {@code PacketWriting#writeCompressedFormat} performs above the compression threshold, and the + * final trimmed copy of the framed buffer. + *

+ * + * @return the framed buffer, whose readable bytes are what the socket would carry + */ + @Benchmark + public NetworkBuffer serializeOneChunkPacket() { + return serialize(this.prebuilt); + } + + /** + * Measures the build and the serialisation of one chunk packet together. + *

+ * The sum of the two methods above and the per chunk unit of the resend. With the packet cache + * enabled this is exactly the work {@code CachedPacket#updatedCache} performs behind one call to + * {@code getFullDataPacket} when its soft reference is empty. + *

+ * + * @return the framed buffer of the chunk + */ + @Benchmark + public NetworkBuffer buildAndSerializeOneChunkPacket() { + return serialize(buildPacket(this.column[0])); + } + + /** + * Measures a full resend: building and serialising a packet for every one of the + * {@code 441} chunks a player at view distance {@code 10} holds. + *

+ * This is the number the SharedInstance decision is made on. It is one operation, not + * {@code 441}, so the reported score is the price of a single instance change and + * needs no multiplication — and it is measured over distinct chunks, so it includes the memory + * traffic of walking a whole column rather than the cache resident cost of one chunk repeated. + *

+ *

+ * The returned sum is the byte volume of the resend. It exists to keep the framed buffers alive + * until the end of the loop, so that no part of the serialisation is eliminated as dead, and it + * is a second, independent statement of the volume the setup already reported. + *

+ * + * @return the total amount of bytes the resend would put on the wire + */ + @Benchmark + public long resendViewDistance10() { + long bytes = 0; + + for (Chunk chunk : this.column) { + bytes += serialize(buildPacket(chunk)).readableBytes(); + } + return bytes; + } + + /** + * Builds the full chunk packet of a chunk. + *

+ * The route is {@code Chunk#getFullDataPacket} followed by + * {@code SendablePacket#extractServerPacket}, because {@code createChunkPacket} is private and + * the {@code CachedPacket} it hangs in is the only handle Minestom offers. With the packet cache + * disabled that pair resolves to a plain call of the supplier, which is the private method + * itself. + *

+ * + * @param chunk the chunk to build the packet of + * @return the built packet + * @throws IllegalStateException if the chunk answers with a packet that cannot be extracted + */ + private static ServerPacket buildPacket(Chunk chunk) { + final SendablePacket sendable = chunk.getFullDataPacket(); + final ServerPacket packet = SendablePacket.extractServerPacket(ConnectionState.PLAY, sendable); + + if (packet == null) { + throw new IllegalStateException("The chunk " + chunk.getChunkX() + ":" + chunk.getChunkZ() + + " answered with " + sendable.getClass().getName() + + ", which holds no extractable packet, so the build cannot be measured"); + } + return packet; + } + + /** + * Serialises, frames and compresses a packet the way the connection layer does. + * + * @param packet the packet to put on the wire + * @return the framed buffer + */ + private NetworkBuffer serialize(ServerPacket packet) { + return PacketWriting.allocateTrimmedPacket(ConnectionState.PLAY, packet, this.compressionThreshold); + } + + /** + * Writes the blocks of the parameter into the source chunk. + * + * @param chunk the chunk to fill + */ + private void applyContent(Chunk chunk) { + switch (this.content) { + case EMPTY -> { + // Nothing is written: a fresh chunk is already air in every position, and every + // MinestomChunks fill refuses to leave a chunk that way on purpose. + } + case UNIFORM -> MinestomChunks.fill(chunk, 1, MinestomChunks.FillShape.UNIFORM); + case TERRAIN -> { + MinestomChunks.fill(chunk, TERRAIN_STATES, MinestomChunks.FillShape.RANDOM_RUNS); + carveSkyAbove(chunk); + } + case DENSE -> MinestomChunks.fill(chunk, DENSE_STATES, MinestomChunks.FillShape.UNIFORM); + } + } + + /** + * Replaces everything above {@code y=64} with air, turning a fully filled chunk into a + * chunk with a surface. + *

+ * This walk is here rather than in {@code MinestomChunks} because the fixture has no Y bounded + * shape: all three of its fills cover the whole column from the bottom of the world to the build + * limit, which is the right choice for a palette or footprint measurement and the wrong one for a + * packet, where the ratio of solid sections to air sections decides both the block data and the + * light. The gap is worth naming rather than working around silently. + *

+ *

+ * The order is Y descending, and that is what keeps the walk affordable. Removing the block that + * currently defines the height of a column sends {@code Heightmap#refresh} back down that column + * until it finds the next matching block ({@code Heightmap.java:40-46}); going downwards means the + * next block is always the one immediately below, so every one of the {@code 65536} writes costs a + * short scan instead of a full column scan. Going upwards would make the same carve quadratic. + *

+ * + * @param chunk the chunk to carve + */ + private static void carveSkyAbove(Chunk chunk) { + final int maxY = chunk.getMaxSection() * Chunk.CHUNK_SECTION_SIZE; + + chunk.lockWriteLock(); + try { + for (int y = maxY - 1; y >= SURFACE_Y; y--) { + for (int z = 0; z < Chunk.CHUNK_SIZE_Z; z++) { + for (int x = 0; x < Chunk.CHUNK_SIZE_X; x++) { + chunk.setBlock(x, y, z, Block.AIR); + } + } + } + } finally { + chunk.unlockWriteLock(); + } + } + + /** + * Fills the sky light of every section the content leaves open to the sky. + *

+ * The array is written through {@code Section#setSkyLight}, which is the same entry point + * {@code Section#clone} and the Anvil loader use, so no light engine has to run and the copies of + * this chunk inherit the light along with the palettes. Every byte is set to {@code -1}, which is + * two nibbles of level {@code 15}; {@code LightCompute#lazyArray} recognises that pattern and + * folds the array into its shared fully lit constant, so seeding {@code 24} sections costs one + * array rather than {@code 24}. + *

+ *

+ * Block light stays untouched and therefore empty. The fixture places no light emitting block, so + * a block light array would be all zeroes, and an all zero array is precisely what + * {@code createLightData} drops from the packet. + *

+ * + * @param chunk the chunk to light + */ + private void seedSkyLight(Chunk chunk) { + final byte[] fullyLit = new byte[LIGHT_ARRAY_LENGTH]; + Arrays.fill(fullyLit, (byte) -1); + + final List
sections = chunk.getSections(); + final int firstLit = firstLitSection(chunk); + + chunk.lockWriteLock(); + try { + for (int index = firstLit; index < sections.size(); index++) { + sections.get(index).setSkyLight(fullyLit); + } + } finally { + chunk.unlockWriteLock(); + } + } + + /** + * Returns the index of the lowest section the content leaves open to the sky. + * + * @param chunk the chunk the index refers to + * @return the first lit section, or the section count if the content is dark throughout + */ + private int firstLitSection(Chunk chunk) { + return switch (this.content) { + case EMPTY -> 0; + case TERRAIN -> Math.floorDiv(SURFACE_Y, Chunk.CHUNK_SECTION_SIZE) - chunk.getMinSection(); + case UNIFORM, DENSE -> chunk.getSections().size(); + }; + } + + /** + * Builds the column of chunks a player at view distance {@code 10} holds. + *

+ * The coordinates come from {@code ChunkRange#chunksInRange}, the very method + * {@code Player#setInstance} uses to decide which chunks to load, so the column is the set the + * slow path would really send rather than a square somebody wrote out by hand. The source chunk + * takes the first coordinate, which the spiral emits as the centre, and every further coordinate + * gets a copy. + *

+ * + * @param source the filled and lit chunk every entry is copied from + * @return the column, with the source as its first entry + * @throws IllegalStateException if the range does not produce {@code 441} coordinates + */ + private Chunk[] buildColumn(Chunk source) { + final List coordinates = new ArrayList<>(RESEND_CHUNKS); + ChunkRange.chunksInRange(0, 0, VIEW_DISTANCE, (chunkX, chunkZ) -> + coordinates.add(new long[]{chunkX, chunkZ})); + + if (coordinates.size() != RESEND_CHUNKS) { + throw new IllegalStateException("The chunk range of view distance " + VIEW_DISTANCE + + " produced " + coordinates.size() + " coordinates instead of " + RESEND_CHUNKS + + ", so the column would not be the set a player receives"); + } + final Chunk[] chunks = new Chunk[RESEND_CHUNKS]; + chunks[0] = source; + + for (int index = 1; index < RESEND_CHUNKS; index++) { + final long[] coordinate = coordinates.get(index); + + source.lockReadLock(); + try { + chunks[index] = source.copy(this.container, (int) coordinate[0], (int) coordinate[1]); + } finally { + source.unlockReadLock(); + } + } + return chunks; + } + + /** + * Verifies that the packet cache is disabled in this fork. + *

+ * Without the flag {@code CachedPacket#packet} would answer from a soft reference and the build + * methods would measure a field read, while the first call after a collection would measure a + * full build. A benchmark that silently degrades into that has no defined meaning, so the trial + * refuses to start. + *

+ * + * @throws IllegalStateException if {@code ServerFlag.CACHED_PACKET} is on + */ + private static void requireDisabledPacketCache() { + if (!ServerFlag.CACHED_PACKET) { + return; + } + throw new IllegalStateException("The packet cache is enabled, so a build cannot be told apart" + + " from a cache hit. Run this benchmark with -Dminestom.cached-packet=false, which" + + " the @Fork annotation of the class normally supplies"); + } + + /** + * Verifies that rebuilding and reserialising the same chunk yields the same bytes. + *

+ * The premise of the measurement: a resend carries data the client already holds. If a rebuild + * produced different bytes, the resend would be necessary rather than redundant and the whole + * question would be malformed. + *

+ * + * @throws IllegalStateException if the two serialisations differ + */ + private void verifyRebuildIsIdentical() { + final byte[] first = bytesOf(this.column[0]); + final byte[] second = bytesOf(this.column[0]); + + if (Arrays.equals(first, second)) { + return; + } + throw new IllegalStateException("Rebuilding the packet of chunk 0:0 produced " + second.length + + " bytes against " + first.length + " bytes before, or the same length with different" + + " content, so a resend would not be redundant work and this benchmark would be" + + " measuring the wrong question (content=" + this.content + ")"); + } + + /** + * Verifies that every chunk of the column serialises to the same uncompressed length. + *

+ * The compressed lengths are deliberately not required to match. The chunk coordinates are part of + * the packet and differ per chunk, and deflate is free to answer a different length for a + * different input, so equality there would be a check on the compressor rather than on the + * fixture. The uncompressed length has no such freedom: it is a pure function of the palettes, the + * heightmaps and the light, all of which the copies share. + *

+ * + * @throws IllegalStateException if two chunks of the column serialise to different lengths + */ + private void verifyColumnIsHomogeneous() { + final long expected = payloadBytesOf(this.column[0]); + + for (int index = 1; index < this.column.length; index++) { + final long actual = payloadBytesOf(this.column[index]); + + if (actual == expected) { + continue; + } + final Chunk chunk = this.column[index]; + throw new IllegalStateException("The chunk " + chunk.getChunkX() + ":" + chunk.getChunkZ() + + " serialises to " + actual + " bytes while the source serialises to " + expected + + ", so the column is not homogeneous and a per chunk average over it would" + + " describe no chunk in particular (content=" + this.content + ")"); + } + } + + /** + * Verifies that a sample of the copies still holds the content of the source. + * + * @param source the chunk every entry of the column was copied from + * @throws IllegalStateException if a sampled copy differs from the source in a block or a height + */ + private void verifyCopiesMatchSource(Chunk source) { + final int last = this.column.length - 1; + final int[] samples = {1, last / 2, last}; + + for (int index = 0; index < COMPARED_COPIES; index++) { + MinestomChunks.assertSameBlocks(source, this.column[samples[index]]); + } + } + + /** + * Verifies that every chunk of the column carries the sky light its content implies. + *

+ * The light is the largest single contributor to the byte volume of the contents that have any, + * and it is inherited through {@code Section#clone} rather than written per chunk, so a fixture + * that lost it would look correct in every block and still report a resend at a fraction of its + * real size. The read goes through {@code Light#array}, which is the same method + * {@code createLightData} uses to decide whether a section contributes bytes at all. + *

+ * + * @throws IllegalStateException if a chunk holds a different amount of lit sections than expected + */ + private void verifySkyLightMatchesContent() { + final int expected = this.column[0].getSections().size() - firstLitSection(this.column[0]); + + for (Chunk chunk : this.column) { + final int actual = litSections(chunk); + + if (actual == expected) { + continue; + } + throw new IllegalStateException("The chunk " + chunk.getChunkX() + ":" + chunk.getChunkZ() + + " carries sky light in " + actual + " sections instead of " + expected + + ", so its packet would not hold the light the content implies (content=" + + this.content + ")"); + } + } + + /** + * Counts the sections of a chunk whose sky light would be written into a chunk packet. + * + * @param chunk the chunk to count in + * @return the amount of sections with a non empty sky light array + */ + private static int litSections(Chunk chunk) { + int lit = 0; + + chunk.lockReadLock(); + try { + for (Section section : chunk.getSections()) { + if (section.skyLight().array().length != 0) { + lit++; + } + } + } finally { + chunk.unlockReadLock(); + } + return lit; + } + + /** + * Prints the byte volume of the column once per trial. + *

+ * The volume is a constant of the fixture rather than a measurement, and JMH reports measurements + * only. It is also the half of the answer that does not depend on the machine the benchmark runs + * on: the microseconds differ per host, the kilobytes do not. Leaving it out of the output would + * mean deriving it from a score, and deriving the primary result of a benchmark is how it gets + * misread. + *

+ */ + private void reportByteVolume() { + final long payloadPerChunk = payloadBytesOf(this.column[0]); + long wireTotal = 0; + long wireMin = Long.MAX_VALUE; + long wireMax = 0; + + for (Chunk chunk : this.column) { + final long wire = serialize(buildPacket(chunk)).readableBytes(); + wireTotal += wire; + wireMin = Math.min(wireMin, wire); + wireMax = Math.max(wireMax, wire); + } + System.out.println("# ChunkResendCostBenchmark" + + " content=" + this.content + + " viewDistance=" + VIEW_DISTANCE + + " chunks=" + RESEND_CHUNKS + + " litSkySections=" + litSections(this.column[0]) + + " compressionThreshold=" + this.compressionThreshold + + " payloadBytesPerChunk=" + payloadPerChunk + + " wireBytesPerChunk=[" + wireMin + ", " + wireMax + "]" + + " payloadBytesPerResend=" + payloadPerChunk * RESEND_CHUNKS + + " wireBytesPerResend=" + wireTotal); + } + + /** + * Returns the framed and compressed bytes of the packet of a chunk. + * + * @param chunk the chunk to serialise + * @return the bytes the socket would carry + */ + private byte[] bytesOf(Chunk chunk) { + final NetworkBuffer buffer = serialize(buildPacket(chunk)); + final byte[] bytes = new byte[(int) buffer.readableBytes()]; + + buffer.copyTo(0, bytes, 0, bytes.length); + return bytes; + } + + /** + * Returns the uncompressed serialised size of the packet of a chunk, without the frame. + *

+ * {@code NetworkBuffer.Type#sizeOf} walks the packet the same way a write does but counts instead + * of storing, so this is the amount of bytes the serializer produced before deflate and before the + * two length prefixes of the compressed frame. + *

+ * + * @param chunk the chunk to measure + * @return the serialised size of its packet in bytes + */ + private long payloadBytesOf(Chunk chunk) { + return ChunkDataPacket.SERIALIZER.sizeOf(asChunkDataPacket(buildPacket(chunk)), this.process); + } + + /** + * Narrows a built packet to the type the chunk path is supposed to produce. + * + * @param packet the packet to narrow + * @return the packet as a {@code ChunkDataPacket} + * @throws IllegalStateException if the chunk produced a packet of another type + */ + private static ChunkDataPacket asChunkDataPacket(ServerPacket packet) { + if (packet instanceof ChunkDataPacket chunkData) { + return chunkData; + } + throw new IllegalStateException("The chunk produced a " + packet.getClass().getName() + + " instead of a ChunkDataPacket, so its size cannot be attributed to a chunk resend"); + } +} diff --git a/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/GeneratorCommitBenchmark.java b/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/GeneratorCommitBenchmark.java new file mode 100644 index 0000000..e89f212 --- /dev/null +++ b/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/GeneratorCommitBenchmark.java @@ -0,0 +1,370 @@ +package net.onelitefeather.falco.benchmark.instance; + +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.Section; +import net.minestom.server.instance.palette.Palette; +import net.onelitefeather.falco.benchmark.support.BenchmarkConstants; +import net.onelitefeather.falco.benchmark.support.MinestomChunks; +import net.onelitefeather.falco.instance.FalcoInstance; +import net.onelitefeather.falco.instance.PaletteCompaction; +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.TearDown; +import org.openjdk.jmh.annotations.Warmup; + +import java.util.ArrayList; +import java.util.List; +import java.util.concurrent.TimeUnit; + +/** + * The {@link GeneratorCommitBenchmark} class measures what it costs to call + * {@code Palette#optimize(Optimization.SIZE)} on the palettes of a chunk a generator has just + * filled, and states that cost next to the copy it follows rather than on its own. + *

+ * The byte side of this question is already answered and is not measured again here. A chunk whose + * sections all ended up in direct mode retains {@code 203 840} bytes against {@code 84 800} for the + * same content stored indirectly, a factor of {@code 2,4}, and {@code Palette#optimize} has no caller + * anywhere in the main source tree of Minestom. What nothing in this repository states is the price + * in time. A saving of more than half the memory of a generated chunk is worth a great deal of time, + * but "a great deal" is not a measurement, and this stage refuses to book a gain whose cost is + * unknown. + *

+ *

+ * What the byte figure does not say, and what this class had to establish before it could measure + * anything, is when the conversion between those two widths is available at all. + * {@code PaletteImpl#downsizeWithPalette} opens with + * {@code if (newBpe >= bpe || newBpe > maxBitsPerEntry) return;}, and {@code maxBitsPerEntry} is + * {@code 8} for blocks. A section that went direct because it genuinely holds more than the + * {@code 256} distinct states an indirect palette can index therefore cannot be brought back, no + * matter how much time is spent on it. {@code optimize} recovers width only where the palette is + * wider than its own content needs. The three parameter values below are chosen to put one trial on + * each side of that line, and the reader of the numbers has to carry the distinction: the factor of + * {@code 2,4} is what the two widths cost, not what this call can move between them. + *

+ * + *

The five arms and why the middle ones exist

+ *

+ * {@link #commitPlain()} copies the staged palettes into the sections of a chunk, which is what + * {@code ChunkGeneration#apply} does today. {@link #commitOptimized()} does the same and then + * optimises each palette it wrote. The difference between the two is the whole answer, and it is a + * difference rather than an absolute on purpose: a number for {@code optimize} alone would be + * compared against nothing, while the commit is the step it was added to. + *

+ *

+ * {@link #commitGuarded()} is the arm this stage ships. It asks {@code PaletteCompaction} whether the + * palette it just wrote can still be narrowed and calls {@code optimize} only then, which is a + * bounded sample of the entries against the full walk {@code optimize} would do before it could reach + * the same conclusion. Its distance from {@link #commitOptimized()} at {@code 1024} distinct states is + * what the guard saves, and its distance at {@code 64} is what the guard costs where it decides to go + * ahead; both belong in the same table, because a guard is only worth reporting with the price it + * charges the case it does not help. + *

+ *

+ * {@link #optimizeAlreadyPacked()} is the control. It optimises palettes which are already at their + * minimum width, which is the case a server pays on every chunk whose generator did not produce a + * wide palette in the first place. Except where those palettes collapsed to the single value mode, + * where {@code optimize} returns on its opening {@code bitsPerEntry == 0}, {@code PaletteImpl#optimize} + * still walks all four thousand and ninety six entries through {@code getAll} to collect the unique + * values before it can decide that there is nothing to do, so this arm is not free and its distance + * from zero is what a generator pays for chunks the optimisation cannot help. + *

+ * + *

Why the state count is the axis

+ *

+ * {@code PaletteImpl#optimize} branches on the number of distinct values it finds: one value collapses + * to the single value mode through {@code fill}, and anything else goes to {@code downsizeWithPalette} + * under {@code Optimization.SIZE}. The cost of the collection walk is the same in both cases and the + * cost of the rewrite is not, so a single state count would answer one of the two questions and hide + * the other. The axis is the one every other chunk benchmark of this module uses, cut down to the + * three points that separate the branches. + *

+ *

+ * The third point separates one branch further, and it is the one the plan needs most. + * {@code 1024} distinct states put every section of the fixture past the indirect ceiling, so + * {@code downsizeWithPalette} returns on its guard and the arm pays the walk and the set for a rewrite + * that never happens. At {@code 1024} the control and the optimised commit therefore measure the same + * work, and that they come out equal is the readout, not a defect: it is the case in which the + * optimisation costs its full price and returns nothing. + *

+ * + *

Why the fixture is re-staged before it is measured

+ *

+ * The chunk this class fills is filled through {@code Chunk#setBlock}, and the palettes that come out + * of it are not the palettes Task 6 will optimise. + * {@link #asAGeneratorWouldHaveWrittenIt(Palette)} states the difference and removes it by rewriting + * the content through {@code Palette#setAll}, the method a generator's commit ends in. It is worth + * naming in one line here as well: a palette grown one block at a time carries at most a bit of slack, + * while a palette a generator wrote is at the direct width whatever it holds. Measuring the first and + * reporting it as the second would have understated both what the optimisation costs and what it + * returns, at two of the three points on the axis. The widths the staging produces are {@code 0} + * against {@code 0} at one state, {@code 15} against {@code 6} at sixty four, and {@code 15} against + * {@code 15} at one thousand and twenty four. + *

+ * + *

Running it

+ * 
{@code
+ * ./gradlew :falco-benchmarks:jmhJar
+ * java -jar falco-benchmarks/build/libs/falco-benchmarks-*-jmh.jar \
+ *     "GeneratorCommitBenchmark" -p distinctStates=1,64,1024 -f 3 -wi 5 -i 5 -prof gc
+ * }
+ *

+ * {@code -prof gc} is not optional. {@code downsizeWithPalette} allocates a new backing array and the + * allocation is part of what the optimisation costs, so a run without the profiler reports half the + * price. + *

+ * + * @author TheMeinerLP + * @version 1.2.1 + * @since 0.4.0 + */ +@State(Scope.Thread) +@BenchmarkMode(Mode.AverageTime) +@OutputTimeUnit(TimeUnit.MICROSECONDS) +@Fork(value = 1, jvmArgsAppend = {"-Xms2g", "-Xmx2g"}) +@Warmup(iterations = 5, time = 1) +@Measurement(iterations = 5, time = 1) +public class GeneratorCommitBenchmark { + + /** + * The amount of distinct block states the staged palettes are filled from. + */ + @Param({"1", "64", "1024"}) + public int distinctStates; + + /** + * The instance the fixture chunks are built in. + */ + private FalcoInstance instance; + + /** + * The palettes at the width a generator would have left them, which every arm copies from and + * never writes to. + */ + private List staged; + + /** + * The same palettes already reduced to their minimum width, for the control arm. + */ + private List packed; + + /** + * The sections the arms commit into, rebuilt per invocation is too slow, so they are reused and + * overwritten; a commit is a full overwrite of every entry, so nothing carries over. + */ + private Section[] target; + + @Setup(Level.Trial) + public void setUp() { + MinestomChunks.ensureServer(); + this.instance = MinestomChunks.newFalcoInstance(); + + final Chunk source = MinestomChunks.newChunk(this.instance, 0, 0); + MinestomChunks.fill(source, this.distinctStates, MinestomChunks.FillShape.RANDOM_RUNS, + BenchmarkConstants.SEED); + + final List
sections = source.getSections(); + + if (sections.size() != BenchmarkConstants.OVERWORLD_SECTIONS) { + throw new IllegalStateException("The fixture chunk holds " + sections.size() + + " sections but the benchmark is written for " + + BenchmarkConstants.OVERWORLD_SECTIONS); + } + this.staged = new ArrayList<>(sections.size()); + this.packed = new ArrayList<>(sections.size()); + this.target = new Section[sections.size()]; + + for (int index = 0; index < sections.size(); index++) { + final Palette blocks = sections.get(index).blockPalette(); + + final Palette alreadyPacked = blocks.clone(); + alreadyPacked.optimize(Palette.Optimization.SIZE); + + this.staged.add(asAGeneratorWouldHaveWrittenIt(blocks)); + this.packed.add(alreadyPacked); + this.target[index] = new Section(); + } + verifyTheFixtureIsStagedLikeAGenerator(); + } + + /** + * Rewrites the content of a section into a fresh palette the way a generator writes it. + *

+ * The fixture is built through {@code Chunk#setBlock}, because that is the only write path every + * chunk type of this module shares, and a palette grown one block at a time is never much wider + * than its content needs. A generator does not write that way and does not leave that shape. + * {@code UnitModifier#setAllRelative} ends in {@code PaletteImpl#setAll}, and that method decides + * between two branches after it has read the whole supplier into its cache: a supplier which + * answered one constant value goes to {@code fill(fillValue)} and leaves the palette in the single + * value mode, and every other supplier goes to {@code makeDirect()} — unconditionally, without + * looking at how many distinct values it actually saw. A generated section is therefore at the + * direct width because of how it was written, not because of what it holds, and that is the whole + * reason {@code optimize} has something to reclaim after a generation and almost nothing to + * reclaim after a sequence of block writes. + *

+ *

+ * Staging the fixture at the width {@code setBlock} produced would measure the optimisation on + * input Task 6 will never hand it. So this method does not imitate either branch — it takes the + * same door the generator takes. {@code Palette#setAll(EntrySupplier)} is public API, the fresh + * {@code Palette.blocks()} below is the palette an unwritten section carries, and the supplier is + * the content of the fixture section. Which of the two branches runs is Minestom's decision here, + * not this class's, and that is what makes {@link #verifyTheFixtureIsStagedLikeAGenerator()} a + * real guard rather than a restatement of a constant: were {@code setAll} to stop calling + * {@code makeDirect}, the staged width would follow it and the guard would say so. Re-enacting the + * branches through {@code Optimization.SPEED} and {@code Optimization.SIZE} — the shape this method + * had before — would have produced the same two widths by construction and could not have noticed. + *

+ * + * @param generated the palette of the fixture section, read and never written + * @return a new palette holding the same content at the width {@code PaletteImpl#setAll} leaves it + */ + private static Palette asAGeneratorWouldHaveWrittenIt(Palette generated) { + final Palette written = Palette.blocks(); + + written.setAll(generated::get); + return written; + } + + @TearDown(Level.Trial) + public void tearDown() { + MinestomChunks.release(this.instance); + this.instance = null; + } + + /** + * Measures the commit as {@code ChunkGeneration#apply} performs it today. + * + * @return the sections that were written, so that nothing can be eliminated + */ + @Benchmark + public Section[] commitPlain() { + for (int index = 0; index < this.target.length; index++) { + this.target[index].blockPalette().copyFrom(this.staged.get(index)); + } + return this.target; + } + + /** + * Measures the same commit with the optimisation this stage adds after it. + * + * @return the sections that were written, so that nothing can be eliminated + */ + @Benchmark + public Section[] commitOptimized() { + for (int index = 0; index < this.target.length; index++) { + final Palette palette = this.target[index].blockPalette(); + palette.copyFrom(this.staged.get(index)); + palette.optimize(Palette.Optimization.SIZE); + } + return this.target; + } + + /** + * Measures the same commit with the guarded optimisation this stage ships. + * + * @return the sections that were written, so that nothing can be eliminated + */ + @Benchmark + public Section[] commitGuarded() { + for (int index = 0; index < this.target.length; index++) { + final Palette palette = this.target[index].blockPalette(); + palette.copyFrom(this.staged.get(index)); + PaletteCompaction.packBlocks(palette); + } + return this.target; + } + + /** + * Measures the guard on palettes that are already at their minimum width. + *

+ * The pair of this arm and {@link #optimizeAlreadyPacked()} is the case a server meets most often + * and the one the plain {@code optimize} call handles worst. A palette that is already as narrow as + * its content allows still costs the full walk before {@code downsizeWithPalette} can say so, while + * the guard needs only enough entries to see that the count is past what the next mode down could + * index — a handful, for a palette that is already at the minimum width. + *

+ * + * @return the sections that were written, so that nothing can be eliminated + */ + @Benchmark + public Section[] packAlreadyPacked() { + for (int index = 0; index < this.target.length; index++) { + final Palette palette = this.target[index].blockPalette(); + palette.copyFrom(this.packed.get(index)); + PaletteCompaction.packBlocks(palette); + } + return this.target; + } + + /** + * Measures the optimisation of palettes that are already at their minimum width. + * + * @return the sections that were written, so that nothing can be eliminated + */ + @Benchmark + public Section[] optimizeAlreadyPacked() { + for (int index = 0; index < this.target.length; index++) { + final Palette palette = this.target[index].blockPalette(); + palette.copyFrom(this.packed.get(index)); + palette.optimize(Palette.Optimization.SIZE); + } + return this.target; + } + + /** + * Refuses a fixture whose palettes are not at a width a generator leaves. + *

+ * This is the guard the benchmark actually needs, and it replaced one that demanded a narrowing. + * Demanding a narrowing looks like the stricter check and is the weaker one. It passes on the + * fixture {@code Chunk#setBlock} produces, where a palette carries a bit of slack and duly narrows + * by that bit, and it aborts the {@code 1024} state trial, where nothing narrows because nothing + * can — which is the single most decision relevant point on the axis. It would therefore have + * waved through the first draft of this class, whose numbers were the cost of shaving one bit off + * an indirect palette reported as the cost of packing a direct one. + *

+ *

+ * What a generator leaves is not a range but two values. {@code PaletteImpl#setAll} sends a + * constant supplier to {@code fill} and everything else to {@code makeDirect}, so every staged + * palette must be either in the single value mode or at the direct width, and any third width means + * the staging stopped producing what a generator produces. Because + * {@link #asAGeneratorWouldHaveWrittenIt(Palette)} calls {@code setAll} itself rather than + * re-enacting its two arms, that covers both ways this can happen: the staging call being dropped, + * and {@code setAll} in a future Minestom no longer widening what it is handed. Both are silent + * failures that turn every number of this class back into a measurement of the wrong input, so both + * stop the run here. + *

+ *

+ * One blind spot is left and is named rather than papered over: at {@code 1024} distinct states the + * fixture is already at the direct width before it is staged, so the two shapes coincide and no + * width can tell them apart. The guard therefore speaks at {@code 1} and at {@code 64} and is + * silent at {@code 1024}. That is enough — a staging that stopped widening would be caught at the + * two lower points of the same run — but it is not the same as a guard that watches every point. + *

+ * + * @throws IllegalStateException if a staged palette is at neither the single value mode nor the + * direct width, which means the fixture is no longer the shape a + * generator hands to the commit + */ + private void verifyTheFixtureIsStagedLikeAGenerator() { + for (int index = 0; index < this.staged.size(); index++) { + final int width = this.staged.get(index).bitsPerEntry(); + + if (width != 0 && width != Palette.BLOCK_PALETTE_DIRECT_BITS) { + throw new IllegalStateException("The staged palette of section " + index + " is " + + width + " bits wide at " + this.distinctStates + " distinct states, but a " + + "generator leaves a section either in the single value mode or at the direct " + + "width of " + Palette.BLOCK_PALETTE_DIRECT_BITS + "; this fixture is the " + + "shape Chunk#setBlock produces, not the shape the commit is handed, and its " + + "numbers would understate both what the optimisation costs and what it saves"); + } + } + } +} diff --git a/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/LazySectionBenchmark.java b/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/LazySectionBenchmark.java new file mode 100644 index 0000000..5ac2ff8 --- /dev/null +++ b/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/LazySectionBenchmark.java @@ -0,0 +1,947 @@ +package net.onelitefeather.falco.benchmark.instance; + +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.InstanceContainer; +import net.minestom.server.instance.Section; +import net.minestom.server.instance.block.Block; +import net.onelitefeather.falco.benchmark.support.BenchmarkConstants; +import net.onelitefeather.falco.benchmark.support.MinestomChunks; +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.OperationsPerInvocation; +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.TearDown; +import org.openjdk.jmh.annotations.Warmup; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; +import java.util.Random; +import java.util.SortedSet; +import java.util.TreeSet; +import java.util.concurrent.TimeUnit; + +/** + * The {@link LazySectionBenchmark} class measures what a chunk pays for holding twenty four eagerly + * allocated sections against what it pays for holding one shared empty section and materialising a + * section only when something is written into it. + *

+ * A {@code DynamicChunk} allocates every one of its sections in its constructor. The three lines + * that do it are {@code var sectionsTemp = new Section[maxSection - minSection];}, + * {@code Arrays.setAll(sectionsTemp, value -> new Section());} and + * {@code this.sections = List.of(sectionsTemp);}. A full height overworld chunk therefore owns + * twenty four {@code Section} records, forty eight palettes and forty eight light objects the moment + * it exists, whether or not a single block was ever written into any of them. In an overworld most + * of those sections stay air for the entire life of the chunk, and that is the observation this + * benchmark is built to price. + *

+ * + *

What the candidate can and cannot be

+ *

+ * The flyweight cannot be a subtype of {@code Section} and cannot be a subtype of {@code Palette}. + * {@code Section} is a {@code record} and therefore final, and {@code Palette} is declared + * {@code sealed interface Palette permits PaletteImpl}, so neither a lazy section nor a lazy palette + * can be handed to Minestom. The only place the pattern fits is one level above: a chunk that owns + * its own section container and answers block level reads and writes from it. {@link LazySections} + * is exactly that container and nothing more, which is why the candidate arm of this benchmark is a + * prototype rather than a call into {@code falco-instance}. + *

+ *

+ * That restriction has a consequence a reader of the numbers has to carry: {@code Chunk#getSection} + * and {@code Chunk#getSections} hand out {@code Section} objects, and every caller of those two + * methods forces a lazy chunk to materialise. The chunk packet builder and the anvil writer are such + * callers. The saving measured here is therefore a saving on the block accessor path, not a saving + * that survives an arbitrary caller reaching into the chunk. + *

+ * + *

Why the materialisation allocates instead of cloning

+ *

+ * The obvious copy on write step is {@code EMPTY.clone()}, and it is the wrong one. + * {@code Section#clone} rebuilds the light through {@code skyLight.set(this.skyLight.array())}, and + * {@code SkyLight#set} stores {@code LightCompute.EMPTY_CONTENT} and marks the borders valid and the + * section as needing to be sent. A section that is about to receive its first block has no valid + * light, so a materialisation through {@code clone} would install a lie together with a reference to + * a shared array. {@code new Section()} produces the same block content, leaves the light unset, and + * allocates less. The candidate therefore materialises with {@code new Section()}. + *

+ *

+ * The same reasoning removes a cost the plan for this measurement expected. A copy on write step is + * normally priced as a {@code long[]} copy, but the empty flyweight has no {@code long[]} at all: + * {@code PaletteImpl} keeps {@code values} at {@code null} while {@code bitsPerEntry == 0} and + * {@code PaletteImpl#clone} returns before it would copy anything. The price of materialising an + * empty section is one {@code Section} record, two {@code PaletteImpl} and two {@code Light} + * objects, all of them without a backing array. Whether that is cheap enough is what + * {@link #firstWriteLazy()} answers, and {@code -prof gc} answers it more precisely than the timer + * does. + *

+ * + *

The three questions and the arms that answer them

+ *

+ * Reading an empty section has to become faster, because the candidate answers it with a + * constant instead of walking into a palette. Reading a full section has to stay identical, + * because a proxy that costs anything in the hot path is not worth the memory it saves. The first + * write to an empty section has to be affordable, because it is the one moment the candidate pays + * for what it saved. {@link #readEmptyEager()} against {@link #readEmptyLazy()} answers the first, + * {@link #readFullEager()} against {@link #readFullLazy()} and {@link #steadyWriteEager()} against + * {@link #steadyWriteLazy()} answer the second for both directions of access, and + * {@link #firstWriteLazy()} against {@link #steadyWriteLazy()} answers the third as a difference + * rather than as an absolute. + *

+ *

+ * The baseline of the first write deserves a word, because the naive one is wrong. A chunk with + * eager sections never performs a materialisation at runtime: it performed all twenty four of them + * in its constructor, which is what {@link #buildSectionsEager()} measures. The runtime baseline the + * candidate has to be compared against is therefore the steady state write, and the materialisation + * premium is the difference between the two. Comparing {@link #firstWriteLazy()} against an eager + * arm that also allocates would compare two allocations and report a premium of zero. + *

+ * + *

Why a third arm keeps the list out of the result

+ *

+ * {@code DynamicChunk} stores its sections in a {@code List.of(...)}, which is an + * {@code ImmutableCollections.ListN} whose {@code get} performs a bounds check against a field + * before it reaches the array. The candidate stores them in a plain {@code Section[]}. Swapping the + * container is not the same change as introducing the flyweight, and a two arm benchmark would + * silently credit the flyweight with whatever the container change is worth. + * {@link #scatteredReadMinestom()} and {@link #buildSectionsMinestom()} reproduce the Minestom + * container exactly, {@link #scatteredReadEager()} and {@link #buildSectionsEager()} keep the eager + * sections but move to the array, and only the difference between those two and the lazy arm belongs + * to the pattern under test. + *

+ * + *

The axis, and which measurements it actually moves

+ *

+ * {@link #emptyPercent} is the share of sections of the measured chunk that hold nothing but air. + * The empty sections are the topmost ones, because that is where they sit in an overworld: terrain + * ends somewhere below the build limit and everything above it is air. Placing them at the top + * rather than spreading them evenly is a deliberate choice, since the scattered read walks the + * container and a run of empty sections is what a real read pattern meets. + *

+ *

+ * The share of {@code 90} is the value the plan for this measurement calls the overworld case, and + * it is the one number in this benchmark that must not be taken on trust. {@code EmptySectionCensusTest} + * in the test source set of this module counts the real share in a real world; until it has been run + * over a world, {@code 90} is an assumption and the curve should be read as one. + *

+ *

+ * The axis only moves two of the measurements. {@link #scatteredReadMinestom()} and its two siblings + * meet a different mixture of empty and full sections at every share, and + * {@link #buildSectionsMinestom()} and its two siblings allocate a different number of sections at + * every share. The per section measurements read and write one empty and one full section that are + * built outside the layout, so they are invariant under the axis and only need to be run once. They + * are built outside the layout for a second reason: at a share of {@code 0} the layout holds no + * empty section at all and at a share of {@code 100} it would hold no full one, so a measurement + * that took its subject from the layout would have no subject at one end of its own axis. + *

+ * + *

Why the arms are proved equal before the first measurement

+ *

+ * A flyweight that is not installed degenerates into the baseline and reports that the pattern + * changes nothing, and a flyweight that returns the wrong constant reports that it is faster at + * answering a different question. {@link #verifyAllArmsAgree()} therefore walks all + * {@code 24 * 16 * 16 * 16} positions of all three arms and throws on the first disagreement, checks + * by identity that every empty slot of the candidate really points at the shared section and that no + * full slot does, and refuses a fixture whose full sections hold a single state or nothing but air. + * The trial dies rather than publishes. + *

+ * + *

Why this benchmark reports nanoseconds

+ *

+ * The convention of this module is {@code MICROSECONDS}, and it is the right unit for the work a + * light engine or a region file does. A single palette read is around two nanoseconds and would be + * printed as {@code 0.002 us/op}, which throws away the digits the comparison consists of. The + * measurement plan for this benchmark asks for nanoseconds per operation, so that is what it reports. + *

+ * + *

Running it

+ *

+ * The fixture starts a Minestom server to resolve the block states of the full sections, so the run + * takes the raised heap the convention prescribes for that case. The single fork the convention + * prescribes with it does not survive contact with the scouting run: that run put the whole start, + * JVM launch and server included, at about {@code 1,3 s} per fork of this class, against the + * {@code 10 s} of iterations a fork runs here, so the reason the convention gives for one fork does + * not apply and the citable runs use three. Two commands, because the two families of measurement + * need different parts of the axis: + *

+ * 
{@code
+ * ./gradlew :falco-benchmarks:jmhJar
+ * java -jar falco-benchmarks/build/libs/falco-benchmarks-*-jmh.jar \
+ *     "LazySectionBenchmark.(scatteredRead|buildSections).*" \
+ *     -p emptyPercent=0,62,90 -f 3 -wi 5 -i 5 -prof gc
+ * java -jar falco-benchmarks/build/libs/falco-benchmarks-*-jmh.jar \
+ *     "LazySectionBenchmark.(readEmpty|readFull|steadyWrite|firstWrite).*" \
+ *     -p emptyPercent=90 -f 3 -wi 5 -i 5 -prof gc
+ * }
+ *

+ * The second command pins the axis to a single value on purpose: those four families do not read the + * layout, so running them at three shares would produce the same number three times. The scouting + * run confirmed it — {@code firstWriteLazy} read {@code 2720,0 B/op} at every one of the three + * shares it was taken at, and the four read and write families read {@code 0 B/op} at all of them. + * {@code -prof gc} is not optional for either command. The allocation rate is the metric that + * answers the memory question directly, and it is the only one of the two that the timer cannot + * distort. + *

+ *

+ * Neither command passes {@code -jvmArgs}. The heap this fixture needs is already in the + * {@code @Fork} annotation as {@code jvmArgsAppend}, and restating it on the command line replaces + * the inherited base arguments instead of adding to them, which is a different JVM configuration + * than the one the annotation describes. The fork count is raised to three on the command line + * because the annotation's single fork measures one JVM launch and reports variance between + * iterations of that one launch as if it were the whole of it. + *

+ * + * @author TheMeinerLP + * @version 1.1.0 + * @since 0.4.0 + */ +@State(Scope.Thread) +@BenchmarkMode(Mode.AverageTime) +@OutputTimeUnit(TimeUnit.NANOSECONDS) +@Fork(value = 1, jvmArgsAppend = {"-Xms2g", "-Xmx2g"}) +@Warmup(iterations = 5, time = 1) +@Measurement(iterations = 5, time = 1) +public class LazySectionBenchmark { + + /** + * The amount of sections a chunk of this benchmark holds. + */ + private static final int SECTION_COUNT = BenchmarkConstants.OVERWORLD_SECTIONS; + + /** + * The edge length of a section in blocks. + */ + private static final int SECTION_SIZE = Chunk.CHUNK_SECTION_SIZE; + + /** + * The state id of air. + *

+ * The value is written down rather than read from {@code Block.AIR.stateId()} because it is the + * constant the candidate returns for a shared section, and a constant that is resolved during + * class initialisation would depend on whether the registry is already up at that point. + * {@link #verifyAllArmsAgree()} checks the value against the registry once the server is + * running, so the shortcut cannot drift away from Minestom unnoticed. + *

+ */ + private static final int AIR_STATE = 0; + + /** + * The amount of distinct block states the full sections of the fixture are filled from. + *

+ * Held constant rather than made an axis. The state count decides the bit width of a palette and + * therefore belongs to the chunk comparison, which owns that axis. Sixty four states put the + * block palette at six bits, which is the indirect mode a real terrain section runs in, and keeps + * this benchmark about the flyweight rather than about the packing. + *

+ */ + private static final int FULL_SECTION_STATES = 64; + + /** + * The arrangement the full sections are filled in. + *

+ * The terrain like shape, because a section that is not empty in an overworld is not a random + * scatter of states but a stack of strata. The other two shapes exist to bracket that one and + * belong to the benchmark that varies them. + *

+ */ + private static final MinestomChunks.FillShape FILL_SHAPE = MinestomChunks.FillShape.RANDOM_RUNS; + + /** + * The amount of positions a single scattered read invocation visits. + */ + private static final int SCATTERED_READS = 1024; + + /** + * The index of the empty section inside the probe container. + */ + private static final int PROBE_EMPTY = 0; + + /** + * The index of the full section inside the probe container. + */ + private static final int PROBE_FULL = 1; + + /** + * The share of sections of the measured chunk that hold nothing but air, in percent. + *

+ * The share is converted into a section count by truncation, so {@code 90} of twenty four + * sections means twenty one empty and three full ones rather than twenty one and a half. The + * exact counts are stated by {@link #verifyAllArmsAgree()} when they do not match what the arms + * were built with. + *

+ * + *

Where {@code 62} comes from, and why it is not {@code 90}

+ *

+ * {@code 62} is the only point on this axis that was counted rather than chosen. + * {@code EmptySectionCensusTest} read a generated overworld and found {@code 62,24 %} of the + * sections of its finished chunks to hold nothing but air, over a height profile that leaves no + * doubt about the reading: the sections below world height {@code 64} are empty in {@code 0,0 %} + * of the chunks, the surface transition sits at {@code Y} four to six, and everything above it is + * empty in all of them. + *

+ *

+ * The research report behind this benchmark assumed {@code 90 %} instead, and that number is the + * reason this axis originally stopped there. It came from a world whose chunks are almost all + * air — counting the same share in a void hub world yields {@code 99,6 %}, and counting an + * overworld without regard for how far its generator got yields {@code 87,5 %}, because a chunk + * at {@code minecraft:structure_starts} contributes twenty four empty sections and no terrain. + * Sharing empty sections is worth roughly a third less at the measured point than at the assumed + * one, so the assumed point is kept here only as the upper bound it actually is. + *

+ *

+ * The counted share rests on the {@code 441} finished chunks around the spawn of one world. That + * is a real measurement and a narrow one: an ocean or a mountain range would not produce the same + * share, and no claim beyond "a generated overworld near its spawn" is licensed by it. + *

+ * + *

Why {@code 50} is no longer on this axis

+ *

+ * The axis carried a fourth point, {@code 50}, which was chosen rather than counted and which the + * scouting run of 2026-08-01 showed to be predictable from the other three. That run took + * {@code 0}, {@code 62} and {@code 90} at {@code -f 1 -wi 2 -i 3 -prof gc} and read + * {@code buildSectionsLazy} at {@code 5120,0 B/op}, {@code 2208,0 B/op} and {@code 752,0 B/op}, + * each with an error of at most {@code 0,7 B}. Converted to the full section count the axis + * really varies — twenty four, ten and three — those three points lie exactly on + * {@code 128 + 208 * fullSections}: {@code 128 + 208 * 24 = 5120}, {@code 128 + 208 * 10 = 2208}, + * {@code 128 + 208 * 3 = 752}. The residual is zero at all three, not small at all three. + *

+ *

+ * {@code 50} truncates to twelve empty and twelve full sections, so the line predicts + * {@code 2624 B/op} for it. A point that an exact affine fit through three measured points + * already names cannot disagree with the fit without disproving the fit, and it lies between + * {@code 62} and {@code 0} rather than beyond either of them, so it does not extend the span + * either. It was removed because it costs thirteen further trials — one per benchmark method — + * and answers nothing the remaining three do not. + *

+ *

+ * The three that stay each answer something the others cannot. {@code 0} is the control that + * prices the candidate where sharing can win nothing, and it is the point that showed the lazy + * arm to cost {@code 16 B} more than the eager one rather than the same + * ({@code 5120,0} against {@code 5104,0}). {@code 62} is the only counted point. {@code 90} is + * the upper bound the research report assumed, kept so the assumption can be read against the + * measurement. Allocation is the metric this reasoning rests on because it is the one the + * scouting run could resolve — the same rows carried time errors between {@code 16 %} and + * {@code 230 %} of their own means, and nothing may be concluded from those. + *

+ */ + @Param({"0", "62", "90"}) + public int emptyPercent; + + /** + * The instance the fixture chunk is created in. + */ + private InstanceContainer container; + + /** + * The sections of the baseline arm in the container Minestom uses. + */ + private List
minestomSections; + + /** + * The sections of the baseline arm in a plain array, which isolates the container change. + */ + private Section[] eagerSections; + + /** + * The sections of the candidate arm, with the shared section in every empty slot. + */ + private LazySections lazySections; + + /** + * The probe container of the baseline arm, holding one empty and one full section. + */ + private Section[] probeEager; + + /** + * The probe container of the candidate arm, holding the shared section and one full section. + */ + private LazySections probeLazy; + + /** + * The packed positions the scattered read visits. + */ + private int[] scattered; + + /** + * The block states the probe section already holds, so a write cannot grow its palette. + */ + private int[] presentStates; + + /** + * The mask that turns a cursor into an index of {@link #presentStates}. + */ + private int presentStatesMask; + + /** + * The amount of sections the layout holds that are not empty. + */ + private int filledSections; + + /** + * The position the per section measurements read or write next. + */ + private int cursor; + + /** + * Builds the fixture chunk, derives all three arms from it and proves that they agree. + *

+ * The content of the full sections comes from a real chunk that the shared fixture filled, so the + * states are states the registry actually holds and the arrangement is the one every other chunk + * benchmark of this module measures on. Every arm receives its own clone of every full section: + * two arms that shared a section object would report identical numbers for a reason that has + * nothing to do with either of them, and the write measurements would corrupt each other. + *

+ * + * @throws IllegalStateException if the three arms disagree or the fixture degenerated + */ + @Setup(Level.Trial) + public void setUp() { + MinestomChunks.ensureServer(); + this.container = MinestomChunks.newContainer(); + + final Chunk source = MinestomChunks.newChunk(this.container, 0, 0); + MinestomChunks.fill(source, FULL_SECTION_STATES, FILL_SHAPE); + + final List
filled = source.getSections(); + + if (filled.size() != SECTION_COUNT) { + throw new IllegalStateException("The fixture chunk holds " + filled.size() + + " sections but the benchmark is written for " + SECTION_COUNT); + } + final int emptyCount = SECTION_COUNT * this.emptyPercent / 100; + this.filledSections = SECTION_COUNT - emptyCount; + + final Section[] minestomArm = new Section[SECTION_COUNT]; + final Section[] eagerArm = new Section[SECTION_COUNT]; + final Section[] lazyArm = new Section[SECTION_COUNT]; + + // The empty sections are the topmost ones, which is where an overworld keeps them. + for (int index = 0; index < SECTION_COUNT; index++) { + if (index >= this.filledSections) { + minestomArm[index] = new Section(); + eagerArm[index] = new Section(); + lazyArm[index] = LazySections.EMPTY; + continue; + } + final Section content = filled.get(index); + minestomArm[index] = content.clone(); + eagerArm[index] = content.clone(); + lazyArm[index] = content.clone(); + } + this.minestomSections = List.of(minestomArm); + this.eagerSections = eagerArm; + this.lazySections = new LazySections(lazyArm); + + // The probes sit outside the layout so that both of them exist at every share of the axis. + final Section probeContent = filled.getFirst(); + this.probeEager = new Section[]{new Section(), probeContent.clone()}; + this.probeLazy = new LazySections(new Section[]{LazySections.EMPTY, probeContent.clone()}); + + this.presentStates = statesOf(probeContent); + this.presentStatesMask = this.presentStates.length - 1; + this.scattered = drawScatteredPositions(); + + verifyAllArmsAgree(); + } + + /** + * Unregisters the instance the fixture chunk was created in. + */ + @TearDown(Level.Trial) + public void tearDown() { + MinestomChunks.release(this.container); + this.container = null; + } + + /** + * Measures a read from an empty section through the container Minestom uses today. + *

+ * The section exists, so the read walks into its block palette. The palette is in single value + * mode and answers from a field, which is already close to a constant return, and that is exactly + * why this pairing is worth measuring rather than assuming: the candidate saves two dereferences + * and a coordinate validation, not a table lookup. + *

+ * + * @return the state id the section holds at the read position + */ + @Benchmark + public int readEmptyEager() { + final int position = this.cursor++; + return this.probeEager[PROBE_EMPTY].blockPalette() + .get(position & 15, (position >>> 8) & 15, (position >>> 4) & 15); + } + + /** + * Measures a read from an empty section through the candidate, which answers it with a constant. + * + * @return the state id the candidate reports for the shared section + */ + @Benchmark + public int readEmptyLazy() { + final int position = this.cursor++; + return this.lazyProbeGet(PROBE_EMPTY, position); + } + + /** + * Measures a read from a full section through the container Minestom uses today. + * + * @return the state id the section holds at the read position + */ + @Benchmark + public int readFullEager() { + final int position = this.cursor++; + return this.probeEager[PROBE_FULL].blockPalette() + .get(position & 15, (position >>> 8) & 15, (position >>> 4) & 15); + } + + /** + * Measures a read from a full section through the candidate, which has to pay a branch for it. + *

+ * This is the measurement that decides whether the pattern is affordable. Every read of every + * block of every non empty section in the server goes through the branch this method adds, and a + * result outside the error bars of {@link #readFullEager()} means the memory the pattern saves is + * paid for in the hot path. + *

+ * + * @return the state id the section holds at the read position + */ + @Benchmark + public int readFullLazy() { + final int position = this.cursor++; + return this.lazyProbeGet(PROBE_FULL, position); + } + + /** + * Measures a write into a section that is already materialised, through the container Minestom + * uses today. + *

+ * The written state is one the section already holds, so the palette never grows and the + * measurement stays the same from the first invocation to the last. + *

+ */ + @Benchmark + public void steadyWriteEager() { + final int position = this.cursor++; + this.probeEager[PROBE_FULL].blockPalette().set(position & 15, (position >>> 8) & 15, + (position >>> 4) & 15, this.presentStates[position & this.presentStatesMask]); + } + + /** + * Measures a write into a section that is already materialised, through the candidate. + *

+ * The counterpart of {@link #readFullLazy()} for the write path, and the baseline + * {@link #firstWriteLazy()} has to be read against. The branch is taken on the cold side here, so + * the difference to {@link #steadyWriteEager()} is what the pattern costs a server that is past + * the first write into every section it uses. + *

+ */ + @Benchmark + public void steadyWriteLazy() { + final int position = this.cursor++; + this.probeLazy.set(PROBE_FULL, position & 15, (position >>> 8) & 15, + (position >>> 4) & 15, this.presentStates[position & this.presentStatesMask]); + } + + /** + * Measures the materialisation of a shared section together with the write that triggered it. + *

+ * The method deliberately does not store the materialised section back into the container. A + * store would end the state the measurement needs after the first invocation, since the slot + * would no longer be shared and every following invocation would measure + * {@link #steadyWriteLazy()} instead. What is left out is a single array write; what is measured + * is the allocation of a {@code Section}, of two palettes and of two light objects, plus the + * growth of the block palette from single value mode to four bits and the write itself. + *

+ * + * @return the materialised section, so that nothing of it can be eliminated + */ + @Benchmark + public Section firstWriteLazy() { + final int position = this.cursor++; + final Section materialised = new Section(); + materialised.blockPalette().set(position & 15, (position >>> 8) & 15, + (position >>> 4) & 15, this.presentStates[position & this.presentStatesMask]); + return materialised; + } + + /** + * Measures scattered reads over a whole chunk held in the container Minestom uses today. + * + * @return the accumulated state ids, so that no read can be eliminated + */ + @Benchmark + @OperationsPerInvocation(SCATTERED_READS) + public int scatteredReadMinestom() { + final int[] positions = this.scattered; + final List
sections = this.minestomSections; + int sink = 0; + + for (int index = 0; index < positions.length; index++) { + final int packed = positions[index]; + sink ^= sections.get(packed >>> 12).blockPalette() + .get(packed & 15, (packed >>> 8) & 15, (packed >>> 4) & 15); + } + return sink; + } + + /** + * Measures scattered reads over a whole chunk held in a plain array of eager sections. + *

+ * The control arm. Its distance to {@link #scatteredReadMinestom()} is what moving off + * {@code List.of} is worth, and only what is left after subtracting it belongs to the flyweight. + *

+ * + * @return the accumulated state ids, so that no read can be eliminated + */ + @Benchmark + @OperationsPerInvocation(SCATTERED_READS) + public int scatteredReadEager() { + final int[] positions = this.scattered; + final Section[] sections = this.eagerSections; + int sink = 0; + + for (int index = 0; index < positions.length; index++) { + final int packed = positions[index]; + sink ^= sections[packed >>> 12].blockPalette() + .get(packed & 15, (packed >>> 8) & 15, (packed >>> 4) & 15); + } + return sink; + } + + /** + * Measures scattered reads over a whole chunk held by the candidate. + *

+ * The share of the reads that land in a shared section is {@link #emptyPercent} by construction + * of the drawn positions, so this is the measurement in which the axis turns into a curve. + *

+ * + * @return the accumulated state ids, so that no read can be eliminated + */ + @Benchmark + @OperationsPerInvocation(SCATTERED_READS) + public int scatteredReadLazy() { + final int[] positions = this.scattered; + final LazySections sections = this.lazySections; + int sink = 0; + + for (int index = 0; index < positions.length; index++) { + final int packed = positions[index]; + sink ^= sections.get(packed >>> 12, packed & 15, (packed >>> 8) & 15, (packed >>> 4) & 15); + } + return sink; + } + + /** + * Measures the section allocation a {@code DynamicChunk} performs in its constructor. + *

+ * The three lines are copied from {@code DynamicChunk}, down to the {@code Arrays.setAll} and the + * {@code List.of}, because the point of this arm is what the constructor of Minestom costs and + * not what a rewrite of it would cost. + *

+ * + * @return the built sections, so that the allocation cannot be eliminated + */ + @Benchmark + public List
buildSectionsMinestom() { + final Section[] sections = new Section[SECTION_COUNT]; + Arrays.setAll(sections, index -> new Section()); + return List.of(sections); + } + + /** + * Measures the same allocation without the immutable list around it. + * + * @return the built sections, so that the allocation cannot be eliminated + */ + @Benchmark + public Section[] buildSectionsEager() { + final Section[] sections = new Section[SECTION_COUNT]; + Arrays.setAll(sections, index -> new Section()); + return sections; + } + + /** + * Measures what the candidate allocates for a chunk that ends up with the configured share of + * empty sections. + *

+ * A chunk of the candidate allocates nothing at construction: it fills its array with the shared + * section and is done. The sections that are not empty are materialised when the loader writes + * their first block, so the honest comparison against the constructor of Minestom is the array + * plus one materialisation per non empty section. That is what this arm builds, which is why it + * is the one place where {@link #emptyPercent} decides how much memory is touched rather than how + * much is read. + *

+ * + * @return the built container, so that the allocation cannot be eliminated + */ + @Benchmark + public LazySections buildSectionsLazy() { + final Section[] sections = new Section[SECTION_COUNT]; + Arrays.fill(sections, LazySections.EMPTY); + + for (int index = 0; index < this.filledSections; index++) { + sections[index] = new Section(); + } + return new LazySections(sections); + } + + /** + * Reads a position of the probe container of the candidate. + * + * @param section the index of the section inside the probe container + * @param position the packed position the cursor produced + * @return the state id at the position + */ + private int lazyProbeGet(int section, int position) { + return this.probeLazy.get(section, position & 15, (position >>> 8) & 15, (position >>> 4) & 15); + } + + /** + * Draws the positions the scattered read visits. + *

+ * The positions are drawn over the whole chunk and not over the sections separately, so the share + * of reads that meet an empty section is the share of sections that are empty. A benchmark that + * drew the same amount of positions per section would report the same number for every setting of + * the axis and would look like a curve without being one. + *

+ * + * @return the packed positions, section index in the upper bits and the coordinates below it + */ + private int[] drawScatteredPositions() { + final Random random = new Random(BenchmarkConstants.SEED); + final int[] positions = new int[SCATTERED_READS]; + + for (int index = 0; index < positions.length; index++) { + final int section = random.nextInt(SECTION_COUNT); + final int x = random.nextInt(SECTION_SIZE); + final int y = random.nextInt(SECTION_SIZE); + final int z = random.nextInt(SECTION_SIZE); + positions[index] = (section << 12) | (y << 8) | (z << 4) | x; + } + return positions; + } + + /** + * Collects the distinct block states a section holds, rounded down to a power of two. + *

+ * The write measurements pick their state from this set so that the palette of the section can + * never grow while they run. A palette that grew during a measurement would report the cost of a + * resize as if it were the cost of a write. The length is rounded down to a power of two so the + * pick is a mask rather than a division, which keeps the arithmetic out of the result. + *

+ * + * @param section the section to collect from + * @return the collected states + * @throws IllegalStateException if the section holds fewer than two distinct states + */ + private static int[] statesOf(Section section) { + final SortedSet distinct = new TreeSet<>(); + section.blockPalette().getAll((x, y, z, value) -> distinct.add(value)); + + if (distinct.size() < 2) { + throw new IllegalStateException("The fixture section holds " + distinct.size() + + " distinct states, so a measurement on it would measure a uniform palette"); + } + final List ordered = new ArrayList<>(distinct); + int length = Integer.highestOneBit(ordered.size()); + final int[] states = new int[length]; + + for (int index = 0; index < length; index++) { + states[index] = ordered.get(index); + } + return states; + } + + /** + * Proves that the three arms hold the same chunk before a single measurement is taken. + *

+ * The walk covers every position of every section of all three arms, so a slot that received the + * wrong content and a candidate that returns the wrong constant are both caught rather than + * measured. The checks around it cover the failures the walk cannot see: a candidate whose shared + * slots were quietly replaced by ordinary sections would pass the walk and report that the + * pattern is free, and a fixture whose fill did not take would pass it and report the best + * numbers this benchmark will ever produce for a chunk that holds nothing. + *

+ * + * @throws IllegalStateException if the arms disagree, the sharing is not installed, the state id + * of air is not the constant the candidate returns or the full + * sections degenerated to a single state + */ + private void verifyAllArmsAgree() { + if (Block.AIR.stateId() != AIR_STATE) { + throw new IllegalStateException("Air has the state id " + Block.AIR.stateId() + + " but the candidate answers a shared section with " + AIR_STATE); + } + for (int section = 0; section < SECTION_COUNT; section++) { + final boolean shared = this.lazySections.isShared(section); + + if (shared != (section >= this.filledSections)) { + throw new IllegalStateException("The section " + section + " of the candidate is " + + (shared ? "shared" : "materialised") + " but the layout for " + this.emptyPercent + + " percent empty sections asks for the opposite"); + } + for (int y = 0; y < SECTION_SIZE; y++) { + for (int z = 0; z < SECTION_SIZE; z++) { + for (int x = 0; x < SECTION_SIZE; x++) { + final int minestom = this.minestomSections.get(section).blockPalette().get(x, y, z); + final int eager = this.eagerSections[section].blockPalette().get(x, y, z); + final int lazy = this.lazySections.get(section, x, y, z); + + if (minestom != eager || minestom != lazy) { + throw new IllegalStateException("The arms disagree at section " + section + + " position " + x + ":" + y + ":" + z + ": minestom " + minestom + + ", eager " + eager + ", lazy " + lazy); + } + } + } + } + } + verifyProbesAgree(); + } + + /** + * Proves that the two probe containers hold the same empty and the same full section. + * + * @throws IllegalStateException if the probes disagree or the full probe holds nothing but air + */ + private void verifyProbesAgree() { + if (!this.probeLazy.isShared(PROBE_EMPTY) || this.probeLazy.isShared(PROBE_FULL)) { + throw new IllegalStateException("The probe container of the candidate does not share its " + + "empty section or shares its full one"); + } + boolean foundNonAir = false; + + for (int y = 0; y < SECTION_SIZE; y++) { + for (int z = 0; z < SECTION_SIZE; z++) { + for (int x = 0; x < SECTION_SIZE; x++) { + final int emptyEager = this.probeEager[PROBE_EMPTY].blockPalette().get(x, y, z); + final int emptyLazy = this.probeLazy.get(PROBE_EMPTY, x, y, z); + final int fullEager = this.probeEager[PROBE_FULL].blockPalette().get(x, y, z); + final int fullLazy = this.probeLazy.get(PROBE_FULL, x, y, z); + + if (emptyEager != AIR_STATE || emptyLazy != AIR_STATE) { + throw new IllegalStateException("The empty probe holds " + emptyEager + " and " + + emptyLazy + " at " + x + ":" + y + ":" + z + " instead of air"); + } + if (fullEager != fullLazy) { + throw new IllegalStateException("The full probes disagree at " + x + ":" + y + ":" + + z + ": eager " + fullEager + ", lazy " + fullLazy); + } + foundNonAir |= fullEager != AIR_STATE; + } + } + } + if (!foundNonAir) { + throw new IllegalStateException("The full probe holds nothing but air over all " + + BenchmarkConstants.BLOCK_ENTRIES + " positions"); + } + } + + /** + * The {@link LazySections} class is the section container of the candidate arm: an array in which + * every section that holds nothing but air is one and the same shared object, and in which a + * section is created only when something is written into it. + *

+ * The class is a prototype and lives here rather than in {@code falco-instance} because nothing + * of it can be handed to Minestom. {@code Section} is a record and {@code Palette} is a sealed + * interface, so the pattern cannot be expressed as a subtype of either, and a chunk that wanted + * it would have to own its section container and answer {@code getBlock} and {@code setBlock} + * from it. Measuring the container in isolation says whether that rewrite is worth starting. + *

+ *

+ * The shared section is a {@code static final} field on purpose. It makes the identity comparison + * in {@link #get(int, int, int, int)} a comparison against a constant the compiler knows, which is + * the cheapest form the check can take and therefore the form the measurement has to use. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ + public static final class LazySections { + + /** + * The section every empty slot of every container points at. + *

+ * It is never written to. {@link #set(int, int, int, int, int)} replaces the slot before it + * writes, which is the copy on write step of the pattern. + *

+ */ + static final Section EMPTY = new Section(); + + /** + * The sections, with {@link #EMPTY} in every slot that holds nothing but air. + */ + private final Section[] sections; + + /** + * Creates a container around the given sections. + * + * @param sections the sections, with {@link #EMPTY} in every empty slot + */ + LazySections(Section[] sections) { + this.sections = sections; + } + + /** + * Reads a block state. + * + * @param section the index of the section inside the container + * @param x the x coordinate inside the section + * @param y the y coordinate inside the section + * @param z the z coordinate inside the section + * @return the state id at the position + */ + int get(int section, int x, int y, int z) { + final Section stored = this.sections[section]; + + if (stored == EMPTY) { + return AIR_STATE; + } + return stored.blockPalette().get(x, y, z); + } + + /** + * Writes a block state, materialising the section if it is still the shared one. + *

+ * The materialisation allocates a new section rather than cloning the shared one. Cloning + * would carry the light state of the shared section over, and the shared section claims a + * light it does not have as soon as {@code Section#clone} has run through + * {@code SkyLight#set}. A freshly allocated section holds the same blocks and no light, which + * is what a section that is about to receive its first block has to hold. + *

+ * + * @param section the index of the section inside the container + * @param x the x coordinate inside the section + * @param y the y coordinate inside the section + * @param z the z coordinate inside the section + * @param state the state id to write + */ + void set(int section, int x, int y, int z, int state) { + Section stored = this.sections[section]; + + if (stored == EMPTY) { + stored = new Section(); + this.sections[section] = stored; + } + stored.blockPalette().set(x, y, z, state); + } + + /** + * Reports whether a slot still points at the shared section. + * + * @param section the index of the section inside the container + * @return whether the slot is shared + */ + boolean isShared(int section) { + return this.sections[section] == EMPTY; + } + } +} diff --git a/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/PaletteIndirectGetBenchmark.java b/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/PaletteIndirectGetBenchmark.java new file mode 100644 index 0000000..ed6dd5e --- /dev/null +++ b/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/PaletteIndirectGetBenchmark.java @@ -0,0 +1,602 @@ +package net.onelitefeather.falco.benchmark.instance; + +import it.unimi.dsi.fastutil.ints.Int2IntOpenHashMap; +import it.unimi.dsi.fastutil.ints.IntArrayList; +import it.unimi.dsi.fastutil.ints.IntOpenHashSet; +import net.minestom.server.instance.palette.Palette; +import net.minestom.server.instance.palette.Palettes; +import net.onelitefeather.falco.benchmark.support.BenchmarkConstants; +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.Warmup; + +import java.util.Arrays; +import java.util.Random; +import java.util.concurrent.TimeUnit; + +/** + * The {@link PaletteIndirectGetBenchmark} class measures the indirect storage model of the Minestom + * block palette: the cost of reading through it, the cost of looking a block state up in it, and the + * cost of growing it, each against a plain array structure that serves the same purpose. + *

+ * Minestom carries palette benchmarks of its own. What they do not carry is the indirect path at the + * widths between {@code 5} and {@code 8} bits, and the growth of the palette in isolation from the + * remapping of the packed array. Those are the two measurements taken here; everything Minestom + * already measures is deliberately left where it is. + *

+ * + *

Why the fixture is built through load and never through setAll

+ *

+ * {@code Palette#setAll(EntrySupplier)} switches the palette to direct storage the moment the + * supplier returns more than one distinct value. It calls {@code makeDirect} unconditionally in that + * case, which nulls both palette structures and pushes {@code bitsPerEntry} to {@code 15}. A + * benchmark that filled its fixture that way and then called it an indirect benchmark would be + * measuring the direct path under a wrong label, and the wider the palette the more convincing the + * wrong number would look. + *

+ *

+ * {@code Palette#load(int[], long[])} is the path that produces a genuinely indirect palette, and it + * is also the path a chunk read from an Anvil region file actually takes. The width it picks follows + * from the size of the palette array alone, so the parameter of this benchmark is the palette size + * and the width comes along with it: sizes up to {@code 16} give width {@code 4}, then {@code 5}, + * {@code 6}, {@code 7} and finally {@code 8} at {@code 256}. One state more and {@code load} chooses + * direct storage; the setup refuses to run in that case rather than silently measure it. + *

+ * + *

What the alternative structure is, and what it is not

+ *

+ * {@code Palette} is declared {@code public sealed interface Palette permits PaletteImpl}. A second + * palette implementation cannot be written: not by subclassing, not through reflection, not through + * a proxy, because the permits clause is enforced by the verifier rather than by the compiler alone. + * {@link ArrayIndex} is therefore not a palette and does not pretend to be one. It is a standalone + * structure that answers the same two questions a palette answers internally, index to state and + * state to index, out of plain {@code int} arrays instead of an {@code IntArrayList} and an + * {@code Int2IntOpenHashMap}. + *

+ *

+ * It reads the packed data through {@code Palettes#read(int, int, long[], int, int, int)}, the same + * static helper the palette itself reads through, and it shares the very same {@code long[]} that + * the measured palette holds. Unpacking is therefore identical work on both sides by construction, + * and what the two read arms compare is one indirection and nothing else: the palette reaches its + * states through {@code paletteToValueList.elements()}, the alternative holds the {@code int[]} + * directly. If that difference disappears in the noise, the answer is that the forward direction of + * the palette costs nothing worth removing, which is a result and not a failure. + *

+ *

+ * The reverse direction is where the two structures genuinely differ. The palette hashes, through + * {@code Int2IntOpenHashMap#putIfAbsent}, which is what {@code valueToPaletteIndex} calls even when + * the state is already known. The alternative runs a binary search over a sorted copy of the states + * and reads the palette index out of a parallel array. A hash lookup is a constant amount of work on + * one cache line, a binary search over {@code 256} entries is eight dependent loads over a kilobyte; + * whichever wins, the palette sizes at which it wins are the point of the size axis. + *

+ * + *

Why the growth arm keeps the packed array out of it

+ *

+ * Adding an unknown state to a palette does three things: it inserts into both index structures, it + * may widen the palette, and widening remaps all {@code 4096} entries of the packed array. The third + * is the same work for any index structure, so measuring it would add a constant to both sides and + * bury the difference under it. The growth arm therefore builds the index structures alone, from + * empty to the parameterised size, and the remap is left to the sibling benchmark that measures + * {@code optimize}. + *

+ *

+ * That decision also fixes which alternative can be measured here. A structure that keeps its + * palette in sorted order needs a single array for both directions and is the smallest of all, but + * every insertion in the middle shifts the palette indices behind it and forces a remap of the + * packed array that Minestom would not have done. It is therefore not comparable in a growth arm + * that excludes the remap, and it is left to the footprint measurement, where the remap does not + * exist. What is measured here is the alternative that keeps the palette in insertion order and pays + * for the reverse direction with a sorted side index, so that the packed array is untouched on both + * sides and the numbers describe the same task. + *

+ * + *

Both sides have to agree

+ *

+ * Every trial checks, before any measurement is taken, that the two structures return the same state + * for all {@code 4096} positions, the same palette index for every state of the palette, and the + * same mapping after being grown from empty, and it fails the trial when they do not. It also checks + * that the palette really is in indirect mode. A faster number must never come from doing something + * else, and the way this particular benchmark could quietly start doing something else is that the + * fixture slides into direct storage. + *

+ * + *

What the numbers mean

+ *

+ * The read and lookup arms perform {@link BenchmarkConstants#BLOCK_ENTRIES} operations per + * invocation, over a shuffled order so that neither structure gets a sequential walk handed to it, + * and the reported time is therefore the time for a whole section rather than for one lookup. The + * growth arm performs as many insertions as the palette size parameter says. Dividing is the reader + * task; multiplying a per lookup figure by a section is what a section costs. + *

+ * + *

Running it

+ *

+ * The benchmark needs no server: a palette resolves nothing through the block registry and the state + * ids are generated. It therefore runs under the two fork configuration of the server free + * benchmarks of this project. + *

+ * 
{@code
+ * java -jar build/libs/falco-*-jmh.jar "PaletteIndirectGetBenchmark" -f 2 -wi 5 -i 5
+ * java -jar build/libs/falco-*-jmh.jar "PaletteIndirectGetBenchmark.(minestom|array)Get" \
+ *     -p paletteSize=16,64,256 -f 2 -wi 5 -i 5
+ * }
+ *

+ * The first line runs the full cross product, which is six methods over six palette sizes. The + * second is the shortest run that still covers the read path at the bottom, the middle and the top + * of the indirect range. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@State(Scope.Thread) +@BenchmarkMode(Mode.AverageTime) +@OutputTimeUnit(TimeUnit.MICROSECONDS) +@Fork(value = 2, jvmArgsAppend = {"-Xms512m", "-Xmx512m"}) +@Warmup(iterations = 5, time = 1) +@Measurement(iterations = 5, time = 1) +public class PaletteIndirectGetBenchmark { + + /** + * The edge length of a block palette, mirrored from {@code Palette.BLOCK_DIMENSION}. + */ + private static final int DIMENSION = Palette.BLOCK_DIMENSION; + + /** + * The smallest amount of bits an indirect block palette uses per entry. + */ + private static final int MIN_BITS = Palette.BLOCK_PALETTE_MIN_BITS; + + /** + * The largest amount of bits an indirect block palette uses per entry. + * One more bit and {@code load} chooses direct storage instead. + */ + private static final int MAX_BITS = Palette.BLOCK_PALETTE_MAX_BITS; + + /** + * The largest block state id the generated palettes draw from. + *

+ * The bound keeps the ids inside the range a real block registry occupies, so that the reverse + * index sees keys of a realistic magnitude and spread rather than a consecutive run, which every + * hash and every binary search would find easier than the real thing. + *

+ */ + private static final int STATE_BOUND = 26_000; + + /** + * The amount of distinct block states the measured palette holds. + *

+ * The ladder is the width ladder in disguise, because {@code load} derives the width from the + * size: {@code 16} gives width {@code 4}, {@code 32} gives {@code 5}, {@code 64} gives {@code 6}, + * {@code 128} gives {@code 7}, and {@code 192} and {@code 256} both give {@code 8}. The last two + * share a width on purpose: they hold the width fixed and vary only the amount of entries in the + * index structures, which is the axis the memory break-even turns on and the one on which a hash + * and a binary search diverge fastest. + *

+ */ + @Param({"16", "32", "64", "128", "192", "256"}) + public int paletteSize; + + private Palette palette; + private ArrayIndex arrayIndex; + private int[] states; + private int[] positions; + private int[] queries; + + /** + * Builds the palette and the alternative structure over the same packed data and verifies that + * they agree before the first measurement is taken. + * + * @throws IllegalStateException if the palette did not end up in indirect mode, or if the two + * structures disagree on any position, any state or any insertion + */ + @Setup(Level.Trial) + public void setUp() { + int bitsPerEntry = naturalBits(this.paletteSize); + if (bitsPerEntry > MAX_BITS) { + throw new IllegalStateException("A palette of " + this.paletteSize + + " states does not fit into the indirect mode, which stops at width " + MAX_BITS); + } + + this.states = distinctStates(this.paletteSize); + + long[] packed = new long[Palettes.arrayLength(DIMENSION, bitsPerEntry)]; + Random random = new Random(BenchmarkConstants.SEED); + for (int y = 0; y < DIMENSION; y++) { + for (int z = 0; z < DIMENSION; z++) { + for (int x = 0; x < DIMENSION; x++) { + Palettes.write(DIMENSION, bitsPerEntry, packed, x, y, z, random.nextInt(this.paletteSize)); + } + } + } + + this.palette = Palette.blocks(); + this.palette.load(this.states, packed); + if (this.palette.bitsPerEntry() < MIN_BITS || this.palette.bitsPerEntry() > MAX_BITS) { + throw new IllegalStateException("The fixture left the indirect mode: load() chose width " + + this.palette.bitsPerEntry() + " for " + this.paletteSize + " states"); + } + this.arrayIndex = new ArrayIndex(this.states, this.palette.indexedValues(), this.palette.bitsPerEntry()); + + this.positions = shuffledPositions(random); + this.queries = new int[this.positions.length]; + for (int index = 0; index < this.positions.length; index++) { + int position = this.positions[index]; + this.queries[index] = this.palette.get(position & 15, (position >> 8) & 15, (position >> 4) & 15); + } + + verifyBothStructuresAgree(); + } + + /** + * Measures reading a whole section through the palette of Minestom. + * + * @return the sum of the read block states, so that no read can be optimised away + */ + @Benchmark + public int minestomGet() { + Palette palette = this.palette; + int[] positions = this.positions; + int sum = 0; + for (int position : positions) { + sum += palette.get(position & 15, (position >> 8) & 15, (position >> 4) & 15); + } + return sum; + } + + /** + * Measures reading the same section through the array structure, over the very same packed data. + * + * @return the sum of the read block states, so that no read can be optimised away + */ + @Benchmark + public int arrayGet() { + ArrayIndex index = this.arrayIndex; + int[] positions = this.positions; + int sum = 0; + for (int position : positions) { + sum += index.get(position & 15, (position >> 8) & 15, (position >> 4) & 15); + } + return sum; + } + + /** + * Measures the reverse direction of the palette of Minestom, the hashed lookup that every block + * write goes through. + *

+ * The queried states are all present in the palette, which is what keeps + * {@code valueToPaletteIndex} a lookup instead of an insertion, and they are queried in the + * frequency they occur in the section rather than uniformly, because that is the distribution a + * write pattern over a real chunk produces. + *

+ * + * @return the sum of the returned palette indices, so that no lookup can be optimised away + */ + @Benchmark + public int minestomReverseLookup() { + Palette palette = this.palette; + int[] queries = this.queries; + int sum = 0; + for (int state : queries) { + sum += palette.valueToPaletteIndex(state); + } + return sum; + } + + /** + * Measures the reverse direction of the array structure, the binary search over the sorted states. + * + * @return the sum of the returned palette indices, so that no lookup can be optimised away + */ + @Benchmark + public int arrayReverseLookup() { + ArrayIndex index = this.arrayIndex; + int[] queries = this.queries; + int sum = 0; + for (int state : queries) { + sum += index.indexOf(state); + } + return sum; + } + + /** + * Measures growing the index structures of Minestom from empty to the parameterised palette size. + *

+ * The two calls per state are the two the palette makes: {@code putIfAbsent} on the reverse map, + * which is the call that decides whether the state is new, and {@code add} on the forward list. + * Both growth policies are therefore in the measurement, the doubling of the list and the + * rehashing of the map, and the remap of the packed array is in neither. + *

+ * + * @return the built structures, so that the allocation cannot be optimised away + */ + @Benchmark + public Object[] fastutilIndexGrowth() { + int[] states = this.states; + IntArrayList forward = new IntArrayList(); + Int2IntOpenHashMap reverse = new Int2IntOpenHashMap(); + reverse.defaultReturnValue(-1); + for (int index = 0; index < states.length; index++) { + if (reverse.putIfAbsent(states[index], index) == -1) { + forward.add(states[index]); + } + } + return new Object[]{forward, reverse}; + } + + /** + * Measures growing the array structure from empty to the parameterised palette size. + *

+ * This is the arm that has to justify the alternative, because it is the one where a sorted array + * is structurally worse: every insertion shifts the tail of two arrays, which is work that grows + * with the palette while a hash insertion does not. If the shift stays cheap up to the top of the + * indirect range, the smaller structure is free; if it does not, the memory the footprint + * measurement saves has a price and this arm is where it is written down. + *

+ * + * @return the built structure, so that the allocation cannot be optimised away + */ + @Benchmark + public ArrayIndex arrayIndexGrowth() { + int[] states = this.states; + ArrayIndex index = new ArrayIndex(states.length); + for (int state : states) { + index.add(state); + } + return index; + } + + /** + * Verifies that the palette and the array structure describe the same section and the same + * palette, in both directions and after being grown from empty. + *

+ * The check runs once per trial, before any measurement. Without it a change to either side could + * win time by no longer answering the same question, and the specific way this benchmark could + * drift is a fixture that stops being indirect, which the setup already refuses, or an + * alternative structure whose sorted side index is off by one, which nothing else would notice + * because both arms would still return a number. + *

+ * + * @throws IllegalStateException if the two structures disagree anywhere + */ + private void verifyBothStructuresAgree() { + for (int y = 0; y < DIMENSION; y++) { + for (int z = 0; z < DIMENSION; z++) { + for (int x = 0; x < DIMENSION; x++) { + int expected = this.palette.get(x, y, z); + int actual = this.arrayIndex.get(x, y, z); + if (expected != actual) { + throw new IllegalStateException("The structures disagree at " + x + ", " + y + ", " + z + + ": the palette reads " + expected + " and the array reads " + actual); + } + } + } + } + + for (int state : this.states) { + int expected = this.palette.valueToPaletteIndex(state); + int actual = this.arrayIndex.indexOf(state); + if (expected != actual) { + throw new IllegalStateException("The structures disagree on state " + state + + ": the palette maps it to " + expected + " and the array to " + actual); + } + } + + ArrayIndex grown = arrayIndexGrowth(); + if (grown.size() != this.states.length) { + throw new IllegalStateException("Growing the array structure produced " + grown.size() + + " states instead of " + this.states.length); + } + for (int index = 0; index < this.states.length; index++) { + int actual = grown.indexOf(this.states[index]); + if (actual != index) { + throw new IllegalStateException("Growing the array structure assigned state " + this.states[index] + + " the index " + actual + " instead of " + index); + } + } + } + + /** + * Returns the width {@code load} picks for a palette of the given size. + *

+ * The formula repeats what {@code PaletteImpl#load(int[], long[])} does rather than calling the + * internal utility it uses, so that the fixture never silently follows a change of a helper the + * palette itself may stop using. + *

+ * + * @param size the amount of states in the palette + * @return the width in bits + */ + private static int naturalBits(int size) { + if (size <= 1) { + return MIN_BITS; + } + return Math.max(MIN_BITS, Integer.SIZE - Integer.numberOfLeadingZeros(size - 1)); + } + + /** + * Returns distinct block state ids, air first, drawn from the shared seed. + * + * @param count the amount of ids to return + * @return the ids, distinct and in a stable order + */ + private static int[] distinctStates(int count) { + int[] states = new int[count]; + IntOpenHashSet seen = new IntOpenHashSet(count); + Random random = new Random(BenchmarkConstants.SEED); + seen.add(0); + int written = 1; + while (written < count) { + int candidate = 1 + random.nextInt(STATE_BOUND); + if (seen.add(candidate)) { + states[written++] = candidate; + } + } + return states; + } + + /** + * Returns every position of a section, packed as {@code x | z << 4 | y << 8}, in a shuffled order. + *

+ * A sequential walk would hand both structures a prefetch friendly stream of packed longs and + * would hide whatever the two index structures do to the cache, which is the only thing this + * benchmark is about. The order is drawn from the shared seed, so both arms see the same one. + *

+ * + * @param random the generator to draw the order from + * @return the shuffled positions + */ + private static int[] shuffledPositions(Random random) { + int[] positions = new int[BenchmarkConstants.BLOCK_ENTRIES]; + for (int index = 0; index < positions.length; index++) { + positions[index] = index; + } + for (int index = positions.length - 1; index > 0; index--) { + int other = random.nextInt(index + 1); + int swap = positions[index]; + positions[index] = positions[other]; + positions[other] = swap; + } + return positions; + } + + /** + * The {@link ArrayIndex} class answers the two questions a palette answers internally, out of + * plain {@code int} arrays. + *

+ * It is not a {@code Palette} and cannot be one, because that interface is sealed to + * {@code PaletteImpl}. It holds no packed data of its own either: the instance the benchmark + * measures shares the {@code long[]} of the palette it is compared against, so that a read is the + * same unpacking on both sides and only the lookup differs. + *

+ *

+ * Three arrays make up the structure. {@code statesByIndex} is the forward direction and is the + * exact counterpart of {@code paletteToValueList}. {@code sortedStates} and {@code sortedIndices} + * are the reverse direction and together replace {@code valueToPaletteMap}: the first is searched, + * the second says which palette index the found state belongs to. Keeping the palette in + * insertion order is what makes the second array necessary, and it is also what makes an insertion + * cost a shift rather than a remap of the packed array. + *

+ */ + public static final class ArrayIndex { + + private final long[] packed; + private final int bitsPerEntry; + private final int[] statesByIndex; + private final int[] sortedStates; + private final int[] sortedIndices; + private int size; + + /** + * Creates a structure over an existing palette content and its packed data. + * + * @param states the block states in palette order + * @param packed the packed palette indices, shared with the palette it is compared to + * @param bitsPerEntry the width the packed data uses + */ + ArrayIndex(int[] states, long[] packed, int bitsPerEntry) { + this.packed = packed; + this.bitsPerEntry = bitsPerEntry; + this.statesByIndex = states.clone(); + this.sortedStates = states.clone(); + this.sortedIndices = new int[states.length]; + this.size = states.length; + Arrays.sort(this.sortedStates); + for (int index = 0; index < states.length; index++) { + this.sortedIndices[Arrays.binarySearch(this.sortedStates, states[index])] = index; + } + } + + /** + * Creates an empty structure with room for the given amount of states. + *

+ * The capacity is handed in rather than grown, because the growth arm compares insertion + * against insertion and a doubling policy of this structure would be a second variable that + * the fastutil side does not have in the same form. The arrays it is measured against grow on + * their own terms, which is the honest comparison of two designs and not of two capacity + * policies. + *

+ * + * @param capacity the amount of states the structure will hold + */ + ArrayIndex(int capacity) { + this.packed = null; + this.bitsPerEntry = 0; + this.statesByIndex = new int[capacity]; + this.sortedStates = new int[capacity]; + this.sortedIndices = new int[capacity]; + this.size = 0; + } + + /** + * Reads the block state at the given position out of the shared packed data. + * + * @param x the position on the x axis + * @param y the position on the y axis + * @param z the position on the z axis + * @return the block state + */ + public int get(int x, int y, int z) { + return this.statesByIndex[Palettes.read(DIMENSION, this.bitsPerEntry, this.packed, x, y, z)]; + } + + /** + * Returns the palette index of a block state. + * + * @param state the block state to look up + * @return the palette index, or {@code -1} if the state is not in the palette + */ + public int indexOf(int state) { + int found = Arrays.binarySearch(this.sortedStates, 0, this.size, state); + return found < 0 ? -1 : this.sortedIndices[found]; + } + + /** + * Adds a block state and returns the palette index it received. + *

+ * A state that is already known is returned unchanged, which mirrors what + * {@code valueToPaletteIndex} does. A new state is appended to the forward array, which keeps + * every index that was handed out before it valid, and inserted into the sorted arrays at the + * position the search found, which shifts everything behind it. + *

+ * + * @param state the block state to add + * @return the palette index of the state + */ + public int add(int state) { + int found = Arrays.binarySearch(this.sortedStates, 0, this.size, state); + if (found >= 0) { + return this.sortedIndices[found]; + } + int insertion = -(found + 1); + int assigned = this.size; + System.arraycopy(this.sortedStates, insertion, this.sortedStates, insertion + 1, this.size - insertion); + System.arraycopy(this.sortedIndices, insertion, this.sortedIndices, insertion + 1, this.size - insertion); + this.sortedStates[insertion] = state; + this.sortedIndices[insertion] = assigned; + this.statesByIndex[assigned] = state; + this.size = assigned + 1; + return assigned; + } + + /** + * Returns the amount of states the structure holds. + * + * @return the palette size + */ + public int size() { + return this.size; + } + } +} diff --git a/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/SectionAllocationBenchmark.java b/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/SectionAllocationBenchmark.java new file mode 100644 index 0000000..ff93be9 --- /dev/null +++ b/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/SectionAllocationBenchmark.java @@ -0,0 +1,909 @@ +package net.onelitefeather.falco.benchmark.instance; + +import net.minestom.server.coordinate.Point; +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.DynamicChunk; +import net.minestom.server.instance.Instance; +import net.minestom.server.instance.Section; +import net.minestom.server.instance.light.Light; +import net.minestom.server.instance.light.LightCompute; +import net.minestom.server.instance.palette.Palette; +import net.onelitefeather.falco.benchmark.support.BenchmarkConstants; +import net.onelitefeather.falco.benchmark.support.MinestomChunks; +import net.onelitefeather.falco.instance.FalcoInstance; +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.Scope; +import org.openjdk.jmh.annotations.Setup; +import org.openjdk.jmh.annotations.State; +import org.openjdk.jmh.annotations.TearDown; +import org.openjdk.jmh.annotations.Warmup; + +import java.lang.invoke.MethodHandles; +import java.lang.invoke.VarHandle; +import java.util.Arrays; +import java.util.List; +import java.util.Set; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicBoolean; + +/** + * The {@link SectionAllocationBenchmark} class measures what it costs to construct one chunk, and + * splits that cost into the three posts a chunk pays before a single block is written: the sections + * themselves, the palettes inside them and the light carriers hanging off them. + *

+ * A fresh overworld chunk of Minestom allocates 24 {@link Section}s eagerly, each holding two + * {@link Palette}s and two {@link Light} carriers, and each light carrier holds one + * {@link AtomicBoolean} whose only job is to remember whether the section still has to be sent. That + * is 24 sections, 48 palettes, 48 light carriers and 48 atomic booleans, roughly 168 objects, for a + * chunk that is entirely air. This benchmark takes those posts apart one at a time so that the + * numbers say which of them is worth an architecture rather than which of them is easiest to name. + *

+ * + *

What this benchmark decides

+ *

+ * The original claim under investigation was that the 48 atomic booleans are the largest avoidable + * post of a chunk. The adversarial review downgraded it before a line of this class existed: 48 + * atomic booleans are about 768 bytes, while the 48 palette objects alone are roughly 1.9 KiB and + * the 24 sections and 48 light carriers come on top. The suspected lever is therefore the eager + * section array of {@code DynamicChunk}, which fills every one of its slots with a freshly built + * {@code new Section()}. + *

+ *

+ * The two arms that settle this are {@link #packedFlagLight()} and {@link #sharedAirSection()}. The + * first removes nothing but the atomic booleans; the second removes the sections, and with them + * their palettes and light carriers. If the difference between the first and the baseline is small + * while the difference between the second and the baseline is large, the downgrade was right. The + * arms are built so that this comparison cannot be blurred: every arm allocates the same section + * array and wraps it in the same immutable list, so the only thing that varies between two arms is + * the thing the arm is named after. + *

+ * + *

The ladder of arms

+ * + * + * + * + * + * + * + * + *
What each arm allocates per chunk
ArmSectionsPalettesLight carriersAtomic booleans
{@link #minestomDynamicChunk()}24484848
{@link #eagerReplicaLight()}24484848
{@link #packedFlagLight()}2448480
{@link #sharedUnlitLight()}244800
{@link #sharedAirSection()}0000
+ *

+ * {@link #eagerReplicaLight()} measures nothing new on purpose. It is the control: it builds the + * same 24 eager sections as the baseline, but with the light carrier of this class instead of the + * one of Minestom, which holds the same fields in the same shape. Its delta against the baseline has + * to be zero within the error bars. If it is not, the replica is not faithful, and every number this + * class produces about the light carrier is void, because the difference would then include the + * replica rather than the change under test. Without that arm, the delta between the baseline and + * {@link #packedFlagLight()} would mix two causes and could not answer anything. + *

+ * + *

How much of this is Minestom and how much is a prototype

+ *

+ * More of it is Minestom than the plan assumed, and the difference is worth stating exactly. + * {@link Section} of the pinned build is a record, not a class with hidden constructors, so its + * canonical constructor {@code Section(Palette, Palette, Light, Light)} is public, and {@link Light} + * is an ordinary public interface rather than a sealed one. An own light carrier can therefore be + * put inside a real Minestom section. Every arm of this class consequently builds real + * {@link Section}s holding real {@link Palette}s obtained from {@code Palette.blocks()} and + * {@code Palette.biomes()}; only the light carrier is written here. + *

+ *

+ * The chunk type is a prototype, but a thin one: {@code PrototypeChunk} extends {@link DynamicChunk} + * and adds nothing but access to the protected constructor that takes a prepared list of sections. + * Heightmaps, block entity maps, the packet cache, {@code setBlock} and {@code getBlock} are the + * inherited originals, so an arm differs from the baseline in the sections it is handed and in + * nothing else. What is genuinely not measured here is light computation: {@code LightCompute#compute} + * and {@code LightCompute#getLight} are package-private, so the prototypes reproduce the storage + * shape and the flag semantics of {@code BlockLight} and {@code SkyLight}, not their algorithm. + * {@code calculateInternal} and {@code calculateExternal} therefore refuse to run. This benchmark + * constructs chunks and never lights them, so no arm reaches those methods, and one that started to + * would fail loudly instead of silently measuring less work. + *

+ * + *

Why one replica serves as both sky and block light

+ *

+ * {@code BlockLight} and {@code SkyLight} differ in one field: the sky variant carries an extra + * {@code boolean fullyLit}. Both hold three byte array references, one volatile boolean and one + * atomic boolean, which lands them in the same size class under any header layout, because the extra + * boolean falls into alignment padding that already exists. The control arm is what turns that + * sentence from an assumption into a measurement: if the padding argument were wrong, the replica + * would be a size class smaller than the pair it replaces and the control would show it. + *

+ * + *

Why a FalcoInstance owns the chunks

+ *

+ * The constructor of {@link Chunk} registers a viewable with the entity tracker of its instance, + * keyed by the shared instance list of that instance. An {@code InstanceContainer} hands out a new + * unmodifiable list on every call, and the key compares that list by identity, so every constructed + * chunk inserts a new entry into a map that is never cleared. A benchmark that constructs millions of + * chunks against a container would therefore measure a growing hash map, and would eventually run out + * of heap. A {@link FalcoInstance} is not an {@code InstanceContainer}, receives the {@code List.of()} + * singleton and hits the same key every time, so the map holds exactly one entry for the whole run. + * That is why the instance under all arms is a Falco one. It is a fixture decision and not a + * measurement: the instance is identical for every arm and nothing here compares Falco to Minestom. + *

+ * + *

The shared section is only safe because nothing writes

+ *

+ * {@link #sharedAirSection()} points all 24 slots at a single air section that is built once per + * trial. That is the flyweight the plan asks for, and it is sound for a construction measurement + * because every chunk this class builds stays empty and every check only reads. A production chunk + * would need a copy on write branch that materialises the slot before the first write, which costs + * nothing at construction time and is therefore outside what this benchmark can measure. It cannot be + * prototyped inside {@link DynamicChunk} either: the {@code sections} field is a final immutable list, + * so a materialising chunk needs its own storage and its own type. That is a finding about the shape + * of a future chunk, not a gap in this measurement. + *

+ * + *

Every arm has to build the same chunk

+ *

+ * Before the first measurement, the setup builds one chunk per arm and compares each of them against + * the baseline chunk over every block position and both heightmaps through + * {@code MinestomChunks#assertSameBlocks}, and over the section count, the palette state and the light + * level of every position of every section. A mismatch throws and ends the trial. A cheaper arm that + * no longer produces the same chunk is not a cheaper chunk, it is a different one, and a number taken + * from it would compare two worlds instead of two layouts. + *

+ * + *

Hypothesis

+ *

+ * Expected, not measured: the control lands on the baseline; the packed flag saves the 48 atomic + * booleans, about 768 bytes per chunk, and close to nothing in time, because an + * {@link AtomicBoolean} is a plain allocation and not a synchronisation; dropping the light carriers + * saves a multiple of that; and the shared section arm collapses the whole per chunk cost of sections + * to the section array itself. If that ordering holds, the eager sections are the lever and the + * atomic booleans are a rounding error on top of them. + *

+ * + *

Running it

+ *

+ * The allocation profiler is what this benchmark is actually about; the time column mostly reports + * how fast the allocator is. It runs project wide, but is stated here so a single run reproduces the + * numbers: + *

+ * 
{@code
+ * java -jar build/libs/falco-*-jmh.jar "SectionAllocationBenchmark" -prof gc -f 1 -wi 5 -i 5
+ * }
+ *

+ * Because the measured objects are small and numerous, the object header layout moves the result more + * than any single field does. The second run is the one that says by how much: + *

+ * 
{@code
+ * java -jar build/libs/falco-*-jmh.jar "SectionAllocationBenchmark" -prof gc -f 1 -wi 5 -i 5 \
+ *     -jvmArgsAppend -XX:+UseCompactObjectHeaders
+ * }
+ *

+ * The saving of compact headers is zero or eight bytes per class and never a percentage, so the two + * runs have to be reported as two numbers per arm rather than as one number and a factor. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@State(Scope.Thread) +@BenchmarkMode(Mode.AverageTime) +@OutputTimeUnit(TimeUnit.MICROSECONDS) +@Fork(value = 1, jvmArgsAppend = {"-Xms1g", "-Xmx1g"}) +@Warmup(iterations = 5, time = 1) +@Measurement(iterations = 5, time = 1) +public class SectionAllocationBenchmark { + + /** + * The chunk X every arm builds at. + * All arms share it so that the entity tracker of the instance answers from the same key for all + * of them and the key never becomes a difference between two arms. + */ + private static final int CHUNK_X = 0; + + /** + * The chunk Z every arm builds at. + */ + private static final int CHUNK_Z = 0; + + /** + * The amount of blocks a section holds along one axis. + * Used by the equivalence stage to walk the light of a section. + */ + private static final int SECTION_SIZE = Chunk.CHUNK_SECTION_SIZE; + + /** + * The message the prototype carriers refuse their calculate methods with. + */ + private static final String NO_COMPUTATION = + "This light carrier reproduces the storage of Minestom for an allocation benchmark and " + + "cannot compute light, because LightCompute#compute is package-private"; + + /** + * The message the shared carrier refuses every mutating call with. + */ + private static final String SHARED = + "This light carrier is shared by every section of the benchmark and must not be mutated"; + + /** + * The instance every chunk of every arm belongs to. + * See the class documentation for why this is a {@link FalcoInstance} and why that choice does not + * make this a comparison between Falco and Minestom. + */ + private FalcoInstance instance; + + /** + * The amount of sections a chunk of the configured dimension holds. + * Read from the instance rather than assumed, and cross checked against + * {@link BenchmarkConstants#OVERWORLD_SECTIONS}. + */ + private int sectionCount; + + /** + * The single air section all slots of {@link #sharedAirSection()} point at. + * Built once per trial, so its cost is not part of any measurement, which is the whole point of the + * arm. + */ + private Section sharedAir; + + /** + * Builds the instance, derives the section count and proves that all five arms produce the same + * chunk. + * + * @throws IllegalStateException if the dimension does not hold the expected amount of sections or + * if two arms disagree about the chunk they build + */ + @Setup(Level.Trial) + public void setUp() { + MinestomChunks.ensureServer(); + this.instance = MinestomChunks.newFalcoInstance(); + this.sectionCount = this.instance.getCachedDimensionType().height() / SECTION_SIZE; + + if (this.sectionCount != BenchmarkConstants.OVERWORLD_SECTIONS) { + throw new IllegalStateException("The fixture dimension holds " + this.sectionCount + + " sections but the benchmark documents " + BenchmarkConstants.OVERWORLD_SECTIONS + + "; the reported per chunk numbers would not describe an overworld chunk"); + } + this.sharedAir = new Section(); + + verifyEveryArmBuildsTheSameChunk(); + } + + /** + * Releases the instance so the chunks and the tracker entry of this trial do not survive into the + * next one. + */ + @TearDown(Level.Trial) + public void tearDown() { + MinestomChunks.release(this.instance); + this.instance = null; + this.sharedAir = null; + } + + /** + * Measures the baseline: the chunk Minestom builds today, with 24 eager sections, 48 palettes, 48 + * light carriers and 48 atomic booleans. + * + * @return the constructed chunk, returned so the allocation cannot be eliminated + */ + @Benchmark + public Chunk minestomDynamicChunk() { + return new DynamicChunk(this.instance, CHUNK_X, CHUNK_Z); + } + + /** + * Measures the control: the same 24 eager sections as the baseline, but with the light carrier of + * this class, which holds the same fields as the pair it replaces and still allocates one + * {@link AtomicBoolean} each. + *

+ * The delta of this arm against {@link #minestomDynamicChunk()} has to be zero within the error + * bars. It is the arm that decides whether the two arms below are allowed to be read as statements + * about their subject. + *

+ * + * @return the constructed chunk, returned so the allocation cannot be eliminated + */ + @Benchmark + public Chunk eagerReplicaLight() { + final Section[] sections = new Section[this.sectionCount]; + for (int index = 0; index < sections.length; index++) { + sections[index] = new Section(Palette.blocks(), Palette.biomes(), + new ReplicaLight(), new ReplicaLight()); + } + return new PrototypeChunk(this.instance, CHUNK_X, CHUNK_Z, List.of(sections)); + } + + /** + * Measures the first candidate: everything of the control, with the 48 atomic booleans folded into + * a packed integer field per light carrier. + *

+ * Against the control this isolates the atomic booleans and nothing else. The light carrier keeps + * its three byte array references and swaps one reference for one integer, which lands it in the + * same size class, so the whole delta is the 48 objects that are gone. + *

+ * + * @return the constructed chunk, returned so the allocation cannot be eliminated + */ + @Benchmark + public Chunk packedFlagLight() { + final Section[] sections = new Section[this.sectionCount]; + for (int index = 0; index < sections.length; index++) { + sections[index] = new Section(Palette.blocks(), Palette.biomes(), + new PackedFlagLight(), new PackedFlagLight()); + } + return new PrototypeChunk(this.instance, CHUNK_X, CHUNK_Z, List.of(sections)); + } + + /** + * Measures the second candidate: 24 eager sections with real palettes, but no light carrier of + * their own, pointing at a stateless shared one instead. + *

+ * Against the control this isolates the 48 light carriers together with their 48 atomic booleans, + * which is what a chunk that creates its light lazily would save. A chunk cannot do that with a + * real {@link Section} once it has to light itself, because the light field of the record is final; + * the arm therefore measures the ceiling of that saving rather than a design that is ready to be + * shipped. + *

+ * + * @return the constructed chunk, returned so the allocation cannot be eliminated + */ + @Benchmark + public Chunk sharedUnlitLight() { + final Section[] sections = new Section[this.sectionCount]; + for (int index = 0; index < sections.length; index++) { + sections[index] = new Section(Palette.blocks(), Palette.biomes(), + SharedUnlitLight.INSTANCE, SharedUnlitLight.INSTANCE); + } + return new PrototypeChunk(this.instance, CHUNK_X, CHUNK_Z, List.of(sections)); + } + + /** + * Measures the third candidate: no section of its own at all, every slot pointing at one shared air + * section. + *

+ * Against the control this isolates the 24 sections with their 48 palettes and 48 light carriers, + * and against {@link #packedFlagLight()} it answers the question this benchmark exists for. The + * section array and its immutable list are still allocated per invocation, exactly as in every + * other arm, so the delta is the content of the array and never its shape. + *

+ * + * @return the constructed chunk, returned so the allocation cannot be eliminated + */ + @Benchmark + public Chunk sharedAirSection() { + final Section[] sections = new Section[this.sectionCount]; + Arrays.fill(sections, this.sharedAir); + return new PrototypeChunk(this.instance, CHUNK_X, CHUNK_Z, List.of(sections)); + } + + /** + * Proves that all five arms build the same chunk before the first measurement is taken. + *

+ * The blocks and both heightmaps are compared through {@code MinestomChunks#assertSameBlocks}, + * which walks every position of the chunk. On top of that the sections are compared directly, + * because two chunks can answer the same to every block read and still differ in what their + * sections hold: a palette that is empty against one that stores the air state explicitly reads the + * same and costs a different amount of memory, and a light carrier that reports a level where the + * baseline reports none would change what the chunk sends without changing what it stores. + *

+ * + * @throws IllegalStateException if any arm disagrees with the baseline + */ + private void verifyEveryArmBuildsTheSameChunk() { + final Chunk baseline = minestomDynamicChunk(); + + assertSameChunk("eagerReplicaLight", baseline, eagerReplicaLight()); + assertSameChunk("packedFlagLight", baseline, packedFlagLight()); + assertSameChunk("sharedUnlitLight", baseline, sharedUnlitLight()); + assertSameChunk("sharedAirSection", baseline, sharedAirSection()); + } + + /** + * Compares one arm against the baseline over its blocks, its heightmaps and its sections. + * + * @param arm the name of the arm, used in the failure message + * @param baseline the chunk the baseline arm built + * @param actual the chunk the compared arm built + * @throws IllegalStateException if the two chunks differ + */ + private void assertSameChunk(String arm, Chunk baseline, Chunk actual) { + MinestomChunks.assertSameBlocks(baseline, actual); + + final List
expectedSections = baseline.getSections(); + final List
actualSections = actual.getSections(); + + if (expectedSections.size() != actualSections.size()) { + throw new IllegalStateException("The arm " + arm + " built " + actualSections.size() + + " sections while the baseline built " + expectedSections.size()); + } + for (int index = 0; index < expectedSections.size(); index++) { + assertSameSection(arm, index, expectedSections.get(index), actualSections.get(index)); + } + } + + /** + * Compares one section of an arm against the matching section of the baseline. + *

+ * The palettes are compared over their dimension, their bit width and their entry count rather than + * over a walk of their values, because the block walk of the caller already covers the values and + * these three are what decides how much the palette costs. The light is compared over every + * position of the section, together with the length of the array it would send and the two flags it + * answers with, since those are the only observable state an unlit carrier has. + *

+ * + * @param arm the name of the arm, used in the failure message + * @param index the index of the section inside the chunk + * @param expected the section of the baseline chunk + * @param actual the section of the compared chunk + * @throws IllegalStateException if the two sections differ + */ + private void assertSameSection(String arm, int index, Section expected, Section actual) { + assertSamePalette(arm, index, "block", expected.blockPalette(), actual.blockPalette()); + assertSamePalette(arm, index, "biome", expected.biomePalette(), actual.biomePalette()); + assertSameLight(arm, index, "sky", expected.skyLight(), actual.skyLight()); + assertSameLight(arm, index, "block", expected.blockLight(), actual.blockLight()); + } + + /** + * Compares one palette of a section against the matching palette of the baseline. + * + * @param arm the name of the arm, used in the failure message + * @param index the index of the section inside the chunk + * @param kind the role of the palette, used in the failure message + * @param expected the palette of the baseline section + * @param actual the palette of the compared section + * @throws IllegalStateException if the two palettes differ + */ + private void assertSamePalette(String arm, int index, String kind, Palette expected, Palette actual) { + if (expected.dimension() == actual.dimension() + && expected.bitsPerEntry() == actual.bitsPerEntry() + && expected.count() == actual.count()) { + return; + } + throw new IllegalStateException("The arm " + arm + " holds a different " + kind + + " palette in section " + index + ": expected dimension " + expected.dimension() + + ", " + expected.bitsPerEntry() + " bits and " + expected.count() + " entries but got " + + actual.dimension() + ", " + actual.bitsPerEntry() + " bits and " + actual.count() + + " entries"); + } + + /** + * Compares one light carrier of a section against the matching carrier of the baseline. + *

+ * {@code requiresSend} is asked once and only on the chunks of this stage, never on a measured one, + * because the call clears the flag it reports. + *

+ * + * @param arm the name of the arm, used in the failure message + * @param index the index of the section inside the chunk + * @param kind the role of the carrier, used in the failure message + * @param expected the light carrier of the baseline section + * @param actual the light carrier of the compared section + * @throws IllegalStateException if the two carriers differ + */ + private void assertSameLight(String arm, int index, String kind, Light expected, Light actual) { + for (int y = 0; y < SECTION_SIZE; y++) { + for (int z = 0; z < SECTION_SIZE; z++) { + for (int x = 0; x < SECTION_SIZE; x++) { + final int expectedLevel = expected.getLevel(x, y, z); + final int actualLevel = actual.getLevel(x, y, z); + + if (expectedLevel == actualLevel) { + continue; + } + throw new IllegalStateException("The arm " + arm + " holds a different " + kind + + " light level in section " + index + " at x=" + x + " y=" + y + " z=" + z + + ": expected " + expectedLevel + " but got " + actualLevel); + } + } + } + if (expected.array().length != actual.array().length) { + throw new IllegalStateException("The arm " + arm + " would send a different " + kind + + " light array for section " + index + ": expected " + expected.array().length + + " bytes but got " + actual.array().length); + } + if (expected.requiresUpdate() != actual.requiresUpdate() || expected.requiresSend() != actual.requiresSend()) { + throw new IllegalStateException("The arm " + arm + " reports different " + kind + + " light flags for section " + index); + } + } + + /** + * The {@link PrototypeChunk} class is a {@link DynamicChunk} that accepts a prepared list of + * sections. + *

+ * It adds no field, no override and no behaviour. Its only reason to exist is that the constructor + * of {@link DynamicChunk} which takes a section list is protected, so the sections of an arm cannot + * be handed to a chunk from the outside. Everything else the chunk does, from the heightmaps over + * the block entity maps to the packet cache, is the inherited original, which is what keeps an arm + * comparable to the baseline. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ + private static final class PrototypeChunk extends DynamicChunk { + + /** + * Creates a chunk over a prepared list of sections. + * + * @param instance the instance the chunk belongs to + * @param chunkX the chunk X + * @param chunkZ the chunk Z + * @param sections the sections the chunk is built over + */ + private PrototypeChunk(Instance instance, int chunkX, int chunkZ, List
sections) { + super(instance, chunkX, chunkZ, sections); + } + } + + /** + * The {@link ReplicaLight} class reproduces the storage of {@code BlockLight} and {@code SkyLight} + * field for field, including the {@link AtomicBoolean} that holds the send flag. + *

+ * It exists so that the arms below it differ from the baseline in one thing at a time. Minestom + * keeps both of its carriers package-private, so an arm that wants to change one field of them has + * to bring its own carrier, and a carrier that is brought in has to be proven equal in footprint + * before any of its variants may be read as a saving. That proof is the control arm. + *

+ *

+ * What is deliberately not reproduced is the light computation. {@code LightCompute#compute} is + * package-private, so this class cannot run the search, and both calculate methods refuse instead + * of returning something cheaper than the original would. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ + private static final class ReplicaLight implements Light { + + /** + * The computed light of the section, null until the section is lit, as in the original. + */ + private byte[] content; + + /** + * The light propagated in from the neighbours, null until the section is lit. + */ + private byte[] contentPropagation; + + /** + * The staging buffer the original swaps in on {@code flip}. + */ + private byte[] contentPropagationSwap; + + /** + * Whether the borders of the section are still valid, volatile as in the original. + */ + private volatile boolean isValidBorders = true; + + /** + * Whether the section still has to be sent, in the one object per flag form under test. + */ + private final AtomicBoolean needsSend = new AtomicBoolean(false); + + @Override + public void flip() { + if (this.contentPropagationSwap != null) { + this.contentPropagation = this.contentPropagationSwap; + } + this.contentPropagationSwap = null; + } + + @Override + public void invalidate() { + this.needsSend.set(true); + this.isValidBorders = false; + this.contentPropagation = null; + } + + @Override + public boolean requiresUpdate() { + return !this.isValidBorders; + } + + @Override + public void set(byte[] copyArray) { + this.content = copyArray; + this.contentPropagation = copyArray; + this.isValidBorders = true; + this.needsSend.set(true); + } + + @Override + public boolean requiresSend() { + return this.needsSend.getAndSet(false); + } + + @Override + public byte[] array() { + return this.content == null ? LightCompute.UNSET_CONTENT : this.content; + } + + @Override + public int getLevel(int x, int y, int z) { + return nibble(this.content, x | (z << 4) | (y << 8)); + } + + @Override + public Set calculateInternal(Palette blockPalette, + int chunkX, int chunkY, int chunkZ, + int[] heightmap, int maxY, + LightLookup lightLookup) { + throw new UnsupportedOperationException(NO_COMPUTATION); + } + + @Override + public Set calculateExternal(Palette blockPalette, + Point[] neighbors, + LightLookup lightLookup, + PaletteLookup paletteLookup) { + throw new UnsupportedOperationException(NO_COMPUTATION); + } + } + + /** + * The {@link PackedFlagLight} class is the {@link ReplicaLight} with its {@link AtomicBoolean} + * folded into a packed integer field that is updated through a {@link VarHandle}. + *

+ * This is the candidate the downgraded claim is about. The carrier trades one reference for one + * integer, which does not change its size class, so the entire difference against the control is + * the 48 atomic booleans a chunk no longer allocates. The atomicity is kept rather than dropped: + * {@code requiresSend} still reads and clears in one step, because the send flag is written by the + * lighting thread and read by the thread that builds the packet, and a benchmark that silently + * removed that guarantee would be comparing a correct chunk against a broken one. + *

+ *

+ * Two bits are enough here, and the same technique scales further than this arm shows: a chunk + * could hold the flags of all 48 carriers in a single long. That variant is not measured, because + * it changes the ownership of the flag as well as its representation and would no longer isolate + * one cause. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ + private static final class PackedFlagLight implements Light { + + /** + * The bit that holds what the original keeps in its atomic boolean. + */ + private static final int NEEDS_SEND = 1; + + /** + * The bit that holds what the original keeps in its volatile boolean. + */ + private static final int VALID_BORDERS = 1 << 1; + + /** + * The handle the flag field is updated through. + */ + private static final VarHandle FLAGS; + + static { + try { + FLAGS = MethodHandles.lookup().findVarHandle(PackedFlagLight.class, "flags", int.class); + } catch (ReflectiveOperationException exception) { + throw new ExceptionInInitializerError(exception); + } + } + + /** + * The computed light of the section, null until the section is lit. + */ + private byte[] content; + + /** + * The light propagated in from the neighbours, null until the section is lit. + */ + private byte[] contentPropagation; + + /** + * The staging buffer the original swaps in on {@code flip}. + */ + private byte[] contentPropagationSwap; + + /** + * Both flags of the original in one field, starting with valid borders and nothing to send. + */ + @SuppressWarnings("unused") + private volatile int flags = VALID_BORDERS; + + @Override + public void flip() { + if (this.contentPropagationSwap != null) { + this.contentPropagation = this.contentPropagationSwap; + } + this.contentPropagationSwap = null; + } + + @Override + public void invalidate() { + update(NEEDS_SEND, VALID_BORDERS); + this.contentPropagation = null; + } + + @Override + public boolean requiresUpdate() { + return ((int) FLAGS.getVolatile(this) & VALID_BORDERS) == 0; + } + + @Override + public void set(byte[] copyArray) { + this.content = copyArray; + this.contentPropagation = copyArray; + update(NEEDS_SEND | VALID_BORDERS, 0); + } + + @Override + public boolean requiresSend() { + int witness = (int) FLAGS.getVolatile(this); + while ((witness & NEEDS_SEND) != 0) { + final int updated = witness & ~NEEDS_SEND; + final int seen = (int) FLAGS.compareAndExchange(this, witness, updated); + + if (seen == witness) { + return true; + } + witness = seen; + } + return false; + } + + @Override + public byte[] array() { + return this.content == null ? LightCompute.UNSET_CONTENT : this.content; + } + + @Override + public int getLevel(int x, int y, int z) { + return nibble(this.content, x | (z << 4) | (y << 8)); + } + + @Override + public Set calculateInternal(Palette blockPalette, + int chunkX, int chunkY, int chunkZ, + int[] heightmap, int maxY, + LightLookup lightLookup) { + throw new UnsupportedOperationException(NO_COMPUTATION); + } + + @Override + public Set calculateExternal(Palette blockPalette, + Point[] neighbors, + LightLookup lightLookup, + PaletteLookup paletteLookup) { + throw new UnsupportedOperationException(NO_COMPUTATION); + } + + /** + * Sets and clears bits of the flag field in one atomic step. + * + * @param set the bits to set + * @param clear the bits to clear + */ + private void update(int set, int clear) { + int witness = (int) FLAGS.getVolatile(this); + while (true) { + final int updated = (witness | set) & ~clear; + + if (updated == witness) { + return; + } + final int seen = (int) FLAGS.compareAndExchange(this, witness, updated); + + if (seen == witness) { + return; + } + witness = seen; + } + } + } + + /** + * The {@link SharedUnlitLight} class is a stateless carrier every section of the + * {@link #sharedUnlitLight()} arm points at. + *

+ * It answers exactly what a freshly constructed carrier of Minestom answers, which is what makes + * that arm pass the equivalence stage: no light anywhere, an empty array, nothing to send and + * nothing to update. It holds no field, so it can be shared, and it is the ceiling of what a chunk + * saves by not creating light carriers until something lights it. + *

+ *

+ * Every mutating method refuses. A shared carrier that accepted a write would corrupt every section + * of every chunk of the run, and a construction benchmark that lit something would no longer be + * measuring construction, so failing is the only honest answer here. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ + private static final class SharedUnlitLight implements Light { + + /** + * The one carrier every section of the arm shares. + */ + private static final SharedUnlitLight INSTANCE = new SharedUnlitLight(); + + /** + * Blocks a second instance because the class is a flyweight. + */ + private SharedUnlitLight() { + } + + @Override + public void flip() { + throw new UnsupportedOperationException(SHARED); + } + + @Override + public void invalidate() { + throw new UnsupportedOperationException(SHARED); + } + + @Override + public boolean requiresUpdate() { + return false; + } + + @Override + public void set(byte[] copyArray) { + throw new UnsupportedOperationException(SHARED); + } + + @Override + public boolean requiresSend() { + return false; + } + + @Override + public byte[] array() { + return LightCompute.UNSET_CONTENT; + } + + @Override + public int getLevel(int x, int y, int z) { + return 0; + } + + @Override + public Set calculateInternal(Palette blockPalette, + int chunkX, int chunkY, int chunkZ, + int[] heightmap, int maxY, + LightLookup lightLookup) { + throw new UnsupportedOperationException(SHARED); + } + + @Override + public Set calculateExternal(Palette blockPalette, + Point[] neighbors, + LightLookup lightLookup, + PaletteLookup paletteLookup) { + throw new UnsupportedOperationException(SHARED); + } + } + + /** + * Reads one light level out of a packed nibble array, in the layout of {@code LightCompute#getLight}. + *

+ * The method of Minestom is package-private, so the layout is repeated here rather than called. It + * is four bits per position, two positions per byte, low nibble first. + *

+ * + * @param content the packed array, null when the section was never lit + * @param index the position inside the section + * @return the light level, zero when the section was never lit or the array is too short + */ + private static int nibble(byte[] content, int index) { + if (content == null || index >>> 1 >= content.length) { + return 0; + } + return (content[index >>> 1] >>> ((index & 1) << 2)) & 0xF; + } +} diff --git a/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/SetBlockContentionBenchmark.java b/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/SetBlockContentionBenchmark.java new file mode 100644 index 0000000..98f904e --- /dev/null +++ b/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/instance/SetBlockContentionBenchmark.java @@ -0,0 +1,630 @@ +package net.onelitefeather.falco.benchmark.instance; + +import net.kyori.adventure.key.Key; +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.InstanceContainer; +import net.minestom.server.instance.block.Block; +import net.minestom.server.instance.block.BlockHandler; +import net.onelitefeather.falco.benchmark.support.MinestomChunks; +import net.onelitefeather.falco.instance.FalcoInstance; +import org.jetbrains.annotations.Nullable; +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.TearDown; +import org.openjdk.jmh.annotations.Threads; +import org.openjdk.jmh.annotations.Warmup; +import org.openjdk.jmh.infra.BenchmarkParams; +import org.openjdk.jmh.infra.Blackhole; +import org.openjdk.jmh.infra.ThreadParams; + +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.LongAdder; + +/** + * The {@link SetBlockContentionBenchmark} class measures how many block writes per second an + * {@link InstanceContainer} and a {@link FalcoInstance} accept while several threads write at once. + *

+ * There is exactly one difference between the two sides that this module can defend with a number, and + * this is it. {@code InstanceContainer#UNSAFE_setBlock} is declared {@code private synchronized}, so the + * monitor it takes is the monitor of the whole instance, and it keeps that monitor over the placement + * rule, over {@code BlockHandler#onPlace} and {@code onDestroy}, over up to six recursive neighbour + * updates, over the serialisation of the block change packet to every viewer and over the event + * dispatch. The read write lock every chunk carries since the pinned Minestom build does not soften + * that: {@code chunk.lockWriteLock()} is taken inside the monitor, so the effective write + * granularity of a Minestom world is the world, not the chunk. {@code FalcoInstance#writeBlock} holds + * the write lock of the touched chunk and nothing else, and it runs the neighbour updates, the packets + * and the event after releasing it. + *

+ *

+ * That is a claim about a lock, and a claim about a lock is only worth what a thread count sweep says + * about it. A single thread cannot tell a coarse lock from a fine one, because an uncontended monitor + * costs almost nothing; the two sides are expected to sit on top of each other at one thread and to + * separate as threads are added. The interesting output of this class is therefore not a pair of + * numbers but a pair of curves over {@code -t 1,2,4,8,16}. + *

+ * + *

Why the mode deviates from the convention of this module

+ *

+ * Every other benchmark here reports {@code Mode.AverageTime} in microseconds, and this one reports + * {@code Mode.Throughput} in operations per second. The deviation is deliberate and it is about what + * the number has to add up to. Under contention the quantity that matters is the work the whole system + * completes, and throughput is the only mode in which that is directly readable: JMH sums the + * operations of all threads, so the number of a sixteen thread run is the number of the system, and + * comparing it against the one thread run of the same arm gives the scaling factor the claim is about. + * {@code AverageTime} would report the latency of a single writer, which under a contended monitor + * degrades by roughly the thread count on both sides and hides whether any additional work got done at + * all. Two arms can have the identical average latency while one of them completes sixteen times as + * much. + *

+ * + *

The three scenarios

+ *

+ * {@link Scenario#DISJOINT_CHUNKS} gives every thread a chunk of its own. Nothing in the data forces + * these writers to wait for each other, so whatever serialisation the measurement shows is the lock + * and only the lock. This is the scenario the hypothesis is written for. + *

+ *

+ * {@link Scenario#SAME_CHUNK} puts every thread into chunk {@code 0:0}, at a position of its own. The + * chunk write lock of Falco now excludes the same set of writers the instance monitor of Minestom + * excludes, so the two critical sections are equally wide. What still differs is how long they + * are held: Falco releases before the neighbour updates, the packet and the event, the + * container releases after them. The scenario therefore separates the two halves of the claim, and it + * is the scenario in which the cost Falco pays for its granularity is offset by nothing at all — if + * Falco loses anywhere it loses here. It is included because a benchmark that only ran the case its + * hypothesis predicts is not a measurement but an illustration. + *

+ *

+ * {@link Scenario#DISJOINT_CHUNKS_WITH_HANDLER} is {@link Scenario#DISJOINT_CHUNKS} with the two + * written blocks carrying a {@link BlockHandler} whose {@code onPlace} burns roughly two microseconds + * of processor time. The two scenarios differ in that handler and in nothing else — same chunks, same + * positions, same block states, same fill, same neighbour updates — so the difference between them is + * attributable to the handler alone. This is the argument rather than a variant of it: the monitor of + * the container is held across {@code onPlace}, which means the hold time of the lock that serialises + * every block write of the world is set by code the container does not own and cannot bound. Two + * microseconds is not an adversarial number. It is what a handler that touches a database, a region + * file or a scoreboard costs, and it is far below what a handler that logs costs. + *

+ * + *

Why the state is shared and not per thread

+ *

+ * The convention of this module is {@code @State(Scope.Thread)}, and it cannot hold here. The subject + * of the measurement is a lock which is per instance, so giving every thread its own instance would + * remove the thing being measured and leave a benchmark that reports the same number for both arms and + * calls it a tie. The instances and the chunks are therefore shared, and the only per thread state is + * the slot index and the write parity, which live in {@link Writer}. + *

+ * + *

Why the written block alternates

+ *

+ * Both implementations carry the same guard against a handler that destroys its own block: a map from + * position to the block currently being written, consulted before the write and returning early when + * the same block is written to the same position again. Minestom clears that map in + * {@code InstanceContainer#tick}, Falco in its own tick. A benchmark harness runs no tick loop — + * {@code MinecraftServer.init()} does not start one — so a benchmark that wrote one constant block to + * one constant position would take the early return on the second operation and measure a map lookup + * for the rest of the run, on both sides, and would report an enormous and completely fictional + * throughput. + *

+ *

+ * Each thread therefore alternates between two block states at its position. The alternation makes the + * guard miss every time, which is the honest path, and it keeps the guard map bounded at one entry per + * written position rather than letting it grow for the whole run. + *

+ * + *

What Falco pays for its granularity, and why this benchmark can show it

+ *

+ * The finer lock is not free, and the cost is visible in the code rather than assumed. The guard map + * of the container is a plain {@link java.util.HashMap} and it is allowed to be one precisely because + * the monitor already excludes every other writer; the guard map of Falco is a + * {@code ConcurrentHashMap} and it is touched by every thread before the chunk lock is taken, so Falco + * pays a concurrent put per write where the container pays a plain one. Under + * {@link Scenario#SAME_CHUNK} that cost is offset by nothing at all, so if Falco loses anywhere it + * will lose there. That is a result about the present implementation and it is reported as one. + *

+ *

+ * A second cost used to stand here and is gone, which is recorded rather than quietly deleted, + * because a reader holding an older run needs to know the arms changed underneath it. Falco resolved + * its chunk through a {@code ConcurrentHashMap} and boxed the index on every write, + * where {@code InstanceContainer} used a primitive keyed map. {@code ChunkRegistry} now holds a + * {@code Long2ObjectSyncMap}, which is the same field {@code InstanceContainer#chunks} is — + * same library, same factory, {@code Long2ObjectSyncMap.hashmap()} on both sides. Chunk resolution is + * therefore no longer a difference between the arms, and a result of this benchmark must not be + * attributed to it. + *

+ * + *

What a losing result would mean

+ *

+ * This benchmark measures an advantage of the {@code falco-instance} module as it exists today. It is + * not evidence for a planned reimplementation and must not be cited as such. Nothing here is arranged + * to make Falco win: both arms run through the public {@code Instance#setBlock(int, int, int, Block)}, + * both get chunks built by the same fixture and filled with the same seeded content, both write the + * same two block states at the same coordinates, and both run with block updates enabled, which is the + * setting under which the container holds its monitor across the neighbour recursion and Falco does + * not. If the curves do not separate under {@link Scenario#DISJOINT_CHUNKS}, then the monitor is not + * the bottleneck this module claims it is, and the correct conclusion is that the claim was wrong — not + * that the harness needs adjusting. + *

+ * + *

What the numbers are and are not

+ *

+ * No result is recorded in this javadoc. The hypothesis is that the two arms sit on top of each other + * at one thread in every scenario, that the container arm stays roughly flat from one thread to sixteen + * under {@link Scenario#DISJOINT_CHUNKS} while the Falco arm rises, that the two arms stay far closer + * to each other under {@link Scenario#SAME_CHUNK} because the shorter hold time is all that is left of + * the difference there, and that the gap under {@link Scenario#DISJOINT_CHUNKS_WITH_HANDLER} grows with + * the burn because the container adds the handler cost to a hold time every other writer waits behind. + * A hypothesis is what all of that is until the run exists. + *

+ *

+ * {@link Blackhole#consumeCPU(long)} burns a number of tokens, not a number of nanoseconds; the + * relation is linear but the constant is a property of the machine. The benchmark calibrates itself: + * at one thread, the reciprocal throughput of {@link Scenario#DISJOINT_CHUNKS_WITH_HANDLER} minus the + * reciprocal throughput of {@link Scenario#DISJOINT_CHUNKS} is the actual per operation cost of the + * burn on the machine that produced the run, and that difference belongs next to any citation of the + * handler scenario. + *

+ * + *

Running it

+ *

+ * A server is started, so the fork count drops to one and the heap is raised, as the convention of this + * module prescribes for that case. The thread count is the axis and has to be swept explicitly, because + * {@code @Threads} is not a parameter JMH can cross: + *

+ * 
{@code
+ * ./gradlew :falco-benchmarks:jmhJar
+ * for t in 1 2 4 8 16; do
+ *   java -jar falco-benchmarks/build/libs/falco-benchmarks-*-jmh.jar \
+ *       "SetBlockContentionBenchmark.(minestom|falco)" \
+ *       -t $t -f 1 -wi 5 -i 5 -prof gc -jvmArgs "-Xms2g -Xmx2g" \
+ *       -rff setblock-contention-t$t.json -rf json
+ * done
+ * }
+ *

+ * The claim is about a monitor, so one run should also carry the evidence that it is a monitor rather + * than merely something slow. The JFR profiler records the Java monitor blocked events, and the class + * that owns the monitor appears in them by name: + *

+ * 
{@code
+ * java -jar falco-benchmarks/build/libs/falco-benchmarks-*-jmh.jar \
+ *     "SetBlockContentionBenchmark.minestom" -p scenario=DISJOINT_CHUNKS_WITH_HANDLER \
+ *     -t 16 -f 1 -wi 5 -i 5 -jvmArgs "-Xms2g -Xmx2g" \
+ *     -prof "jfr:configName=profile;dir=build/jfr"
+ * }
+ * + * @author TheMeinerLP + * @version 1.1.0 + * @since 0.4.0 + */ +@State(Scope.Benchmark) +@BenchmarkMode(Mode.Throughput) +@OutputTimeUnit(TimeUnit.SECONDS) +@Fork(value = 1, jvmArgsAppend = {"-Xms2g", "-Xmx2g"}) +@Warmup(iterations = 5, time = 1) +@Measurement(iterations = 5, time = 1) +@Threads(1) +public class SetBlockContentionBenchmark { + + /** + * The block Y every thread writes at. + *

+ * Well inside the world bounds and well below the surface the fill produces, which keeps both + * heightmaps on their cheap branch: a solid block written below the current height compares and + * returns, while a block written at the current height sends the heightmap back down the column + * with a palette scan per step. The measured operation is supposed to be a block write, not a + * heightmap rescan, and it has to be the same block write on both sides. + *

+ */ + private static final int BLOCK_Y = 64; + + /** + * The lowest chunk relative X and Z a thread may write at. + *

+ * One block away from the chunk border on every side. Block updates are enabled, so every write + * asks its six neighbours whether they want to reshape themselves; a position on the border would + * send that question into a neighbouring chunk, which means a second chunk lock on the Falco side + * and a chunk lookup that may miss on both. Keeping the writes off the border keeps the operation + * of the two arms identical and keeps the scenario axis meaningful. + *

+ */ + private static final int LOCAL_MIN = 1; + + /** + * The amount of chunk relative positions a thread slot may be spread over per axis. + */ + private static final int LOCAL_SPAN = Chunk.CHUNK_SIZE_X - 2 * LOCAL_MIN; + + /** + * The processor tokens {@link BurnHandler} burns per placement. + *

+ * Roughly two microseconds on typical hardware. The exact figure is a property of the machine and + * is read off the run rather than assumed; see the class javadoc. + *

+ */ + private static final long BURN_TOKENS = 2000L; + + /** + * The amount of distinct block states the chunks are filled with before the measurement. + *

+ * A chunk that was never filled holds a palette with {@code bitsPerEntry == 0} and no backing + * array, so the first write into each section pays a resize and every write after it runs against + * a palette no loaded world ever has. Sixteen states put every section into the indirect mode a + * real chunk is in, which is the mode the measured writes should meet. + *

+ */ + private static final int FILL_STATES = 16; + + /** + * The arrangement of the writers over the chunks, and whether their blocks carry a handler. + */ + public enum Scenario { + + /** + * Every thread writes into a chunk of its own, and the written blocks carry no handler. + *

+ * The scenario that isolates the lock. Two writes into two chunks share no data at all, so a + * throughput that stops rising with the thread count has only one remaining explanation. + *

+ */ + DISJOINT_CHUNKS, + + /** + * Every thread writes into chunk {@code 0:0}, each at a position of its own. + *

+ * The control. Here the chunk write lock of Falco excludes exactly the writers the instance + * monitor of Minestom excludes, so the width of the two critical sections is the same and only + * their hold time is not. Whatever remains of the difference in this scenario is the shorter + * hold, and whatever the finer mechanism costs is unmasked, because nothing here offsets it. + *

+ */ + SAME_CHUNK, + + /** + * Like {@link #DISJOINT_CHUNKS}, with a {@link BlockHandler} that burns processor time in + * {@code onPlace}. + *

+ * The handler runs inside the chunk write lock on both sides, because both call + * {@code Chunk#setBlock} there. On the Falco side that is the lock of one chunk and the other + * writers are untouched; on the container side it is inside the instance monitor, so every + * writer of the world waits for it. Whatever this scenario shows over + * {@link #DISJOINT_CHUNKS} is the amount by which foreign code sets the hold time of a lock + * that is not foreign code's to set. + *

+ */ + DISJOINT_CHUNKS_WITH_HANDLER + } + + /** + * The arrangement the measured writes run under. + */ + @Param({"DISJOINT_CHUNKS", "SAME_CHUNK", "DISJOINT_CHUNKS_WITH_HANDLER"}) + public Scenario scenario; + + private InstanceContainer container; + private FalcoInstance falco; + private Block[] blocks; + private int[] slotX; + private int[] slotZ; + private @Nullable BurnHandler handler; + private long placementsAfterSetup; + + /** + * Builds both instances, gives every thread slot its chunk and its position, proves that the two + * sides hold the same world and that a write actually lands, and leaves the guard maps in the state + * the first measured operation expects. + *

+ * The order of the steps is the point of the method. The chunks are loaded and filled first, then + * every slot is primed with the same two writes on both sides, and only then are the two sides + * compared. Comparing before the priming would prove that two empty worlds are equal, which is + * true and useless; comparing after it proves that the very writes the benchmark is about produce + * the same result on both implementations. The comparison throws, so a trial that would have + * published a faster number for a different world stops instead. + *

+ * + * @param params the parameters of the trial, read for the thread count + * @throws IllegalStateException if the thread count exceeds the positions a chunk offers, if a + * primed write did not land, if the two sides disagree about their + * content or if the handler of the scenario was never called + */ + @Setup(Level.Trial) + public void setUp(BenchmarkParams params) { + final int threads = params.getThreads(); + + if (threads > LOCAL_SPAN * LOCAL_SPAN) { + throw new IllegalStateException("A chunk offers " + (LOCAL_SPAN * LOCAL_SPAN) + + " positions away from its border, so " + threads + + " threads cannot be given a position of their own"); + } + MinestomChunks.ensureServer(); + this.container = MinestomChunks.newContainer(); + this.falco = MinestomChunks.newFalcoInstance(); + this.handler = this.scenario == Scenario.DISJOINT_CHUNKS_WITH_HANDLER ? new BurnHandler() : null; + this.blocks = blocksOf(this.handler); + this.slotX = new int[threads]; + this.slotZ = new int[threads]; + + final boolean sameChunk = this.scenario == Scenario.SAME_CHUNK; + final int chunks = sameChunk ? 1 : threads; + final Chunk[] minestomChunks = new Chunk[chunks]; + final Chunk[] falcoChunks = new Chunk[chunks]; + + for (int chunkX = 0; chunkX < chunks; chunkX++) { + minestomChunks[chunkX] = MinestomChunks.loadChunk(this.container, chunkX, 0); + falcoChunks[chunkX] = MinestomChunks.loadChunk(this.falco, chunkX, 0); + MinestomChunks.fill(minestomChunks[chunkX], FILL_STATES, MinestomChunks.FillShape.RANDOM_RUNS); + MinestomChunks.fill(falcoChunks[chunkX], FILL_STATES, MinestomChunks.FillShape.RANDOM_RUNS); + } + for (int slot = 0; slot < threads; slot++) { + final int chunkX = sameChunk ? 0 : slot; + this.slotX[slot] = chunkX * Chunk.CHUNK_SIZE_X + LOCAL_MIN + slot % LOCAL_SPAN; + this.slotZ[slot] = LOCAL_MIN + slot / LOCAL_SPAN; + prime(slot); + } + for (int chunkX = 0; chunkX < chunks; chunkX++) { + MinestomChunks.assertSameBlocks(minestomChunks[chunkX], falcoChunks[chunkX]); + } + verifyHandler(threads); + } + + /** + * Releases both instances and verifies that the handler of the scenario kept being called. + *

+ * The release has to happen even when the verification fails, otherwise a failing trial leaves two + * registered instances and their chunks behind for every trial that follows in the same fork. + *

+ * + * @throws IllegalStateException if the handler of the scenario was not called during the trial + */ + @TearDown(Level.Trial) + public void tearDown() { + try { + final BurnHandler burnHandler = this.handler; + + if (burnHandler != null && burnHandler.placements() <= this.placementsAfterSetup) { + throw new IllegalStateException("The handler was called " + this.placementsAfterSetup + + " times during the setup and not once during the trial, so the scenario " + + this.scenario + " measured the same thing as " + Scenario.DISJOINT_CHUNKS); + } + } finally { + MinestomChunks.release(this.container); + MinestomChunks.release(this.falco); + } + } + + /** + * Measures a block write into the {@link InstanceContainer} of Minestom. + *

+ * The call goes through {@code Instance#setBlock(int, int, int, Block)}, which enables block + * updates. That is the path a placement of a player takes and it is the path over which the + * container holds its monitor across the neighbour recursion. + *

+ * + * @param writer the slot and the write parity of the calling thread + */ + @Benchmark + public void minestom(Writer writer) { + final int slot = writer.slot; + this.container.setBlock(this.slotX[slot], BLOCK_Y, this.slotZ[slot], this.blocks[writer.next()]); + } + + /** + * Measures the same block write into the {@link FalcoInstance}. + * + * @param writer the slot and the write parity of the calling thread + */ + @Benchmark + public void falco(Writer writer) { + final int slot = writer.slot; + this.falco.setBlock(this.slotX[slot], BLOCK_Y, this.slotZ[slot], this.blocks[writer.next()]); + } + + /** + * Writes the alternating sequence of a slot once into both instances and verifies that it landed. + *

+ * The readback is not a formality. Both implementations return early when the same block is written + * to the same position twice without a tick in between, and a harness runs no tick, so a benchmark + * whose writes are swallowed by that guard would measure a map lookup while looking perfectly + * healthy. Priming with both states and checking that the second one is what the instance answers + * with proves that the guard is missing rather than hitting, and it leaves the guard map holding + * the second state so that the first measured operation, which writes the first state, misses too. + *

+ * + * @param slot the thread slot to prime + * @throws IllegalStateException if an instance does not hold the last written block afterwards + */ + private void prime(int slot) { + final int x = this.slotX[slot]; + final int z = this.slotZ[slot]; + + for (Block block : this.blocks) { + this.container.setBlock(x, BLOCK_Y, z, block); + this.falco.setBlock(x, BLOCK_Y, z, block); + } + final Block expected = this.blocks[this.blocks.length - 1]; + requireHolds("InstanceContainer", this.container.getBlock(x, BLOCK_Y, z), expected, x, z); + requireHolds("FalcoInstance", this.falco.getBlock(x, BLOCK_Y, z), expected, x, z); + } + + /** + * Verifies that a primed write is visible in the instance that received it. + * + * @param instance the name of the instance for the failure message + * @param actual the block the instance answers with + * @param expected the block that was written last + * @param x the block X that was written + * @param z the block Z that was written + * @throws IllegalStateException if the instance holds a different block + */ + private static void requireHolds(String instance, Block actual, Block expected, int x, int z) { + if (expected.equals(actual)) { + return; + } + throw new IllegalStateException("The " + instance + " holds " + actual.key().asString() + " at x=" + x + + " y=" + BLOCK_Y + " z=" + z + " instead of the " + expected.key().asString() + + " that was written there, so the write was swallowed and the measurement would not" + + " write a block at all"); + } + + /** + * Verifies that the handler of the scenario was wired to the written blocks, and records how often + * it ran during the setup. + *

+ * A scenario that carries a handler which is never called is silently the scenario without one, and + * the difference between the two is the entire argument of this class. The check is exact enough to + * catch that and loose enough to survive a neighbour update that writes an extra block: every + * primed write must have produced at least one placement, on both sides. + *

+ * + * @param threads the thread count of the trial + * @throws IllegalStateException if the scenario carries a handler that was not called, or if a + * scenario without one wrote blocks that carry a handler anyway + */ + private void verifyHandler(int threads) { + final BurnHandler burnHandler = this.handler; + + if (burnHandler == null) { + if (this.blocks[0].handler() != null || this.blocks[1].handler() != null) { + throw new IllegalStateException("The scenario " + this.scenario + " writes blocks which carry" + + " a handler, so it measures the same thing as " + Scenario.DISJOINT_CHUNKS_WITH_HANDLER); + } + return; + } + final long expected = (long) threads * this.blocks.length * 2L; + this.placementsAfterSetup = burnHandler.placements(); + + if (this.placementsAfterSetup < expected) { + throw new IllegalStateException("The setup wrote " + expected + " blocks carrying a handler but the" + + " handler was called " + this.placementsAfterSetup + " times, so the scenario " + + this.scenario + " does not measure the cost of a handler"); + } + } + + /** + * Returns the two block states the writers alternate between. + *

+ * Stone and dirt: both solid, neither a block entity, and neither of them owns a block placement + * rule, so an enabled block update walks its six neighbours and changes nothing. That keeps the + * measured operation a single block write rather than a recursion of unknown depth, and it keeps + * the recursion depth the same on both arms, which is what makes the arms comparable at all. + *

+ * + * @param handler the handler to attach to both states, null for the scenarios without one + * @return the two states, in the order the writers cycle through them + */ + private static Block[] blocksOf(@Nullable BlockHandler handler) { + if (handler == null) { + return new Block[]{Block.STONE, Block.DIRT}; + } + return new Block[]{Block.STONE.withHandler(handler), Block.DIRT.withHandler(handler)}; + } + + /** + * The per thread part of the state: which slot a thread owns and which of the two blocks it writes + * next. + *

+ * Everything else in this benchmark is shared on purpose, because the lock under measurement is + * shared. These two fields must not be, and they must not sit in an array indexed by thread either: + * sixteen threads incrementing sixteen adjacent array slots would trade the cache line of that + * array between all of them on every operation and would report that as the cost of the block + * write. A JMH thread state is padded, allocated per thread and therefore free of that. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ + @State(Scope.Thread) + public static class Writer { + + /** + * The slot of the owning thread, which selects its chunk and its position. + */ + int slot; + + /** + * The amount of writes the owning thread has performed. + */ + int writes; + + /** + * Reads the slot of the owning thread from the harness. + * + * @param params the thread parameters of the owning thread + */ + @Setup(Level.Trial) + public void setUp(ThreadParams params) { + this.slot = params.getThreadIndex(); + } + + /** + * Returns the index of the block to write next and advances the alternation. + * + * @return {@code 0} or {@code 1}, alternating + */ + int next() { + return this.writes++ & 1; + } + } + + /** + * A {@link BlockHandler} that burns processor time when a block carrying it is placed. + *

+ * The burn sits in {@code onPlace} alone. {@code onDestroy} is reached as well from the second + * write of a position onwards, because the block being replaced carries the same handler, and it is + * left empty so that one measured operation costs exactly one burn. A burn in both would double the + * cost of an operation without making the scenario say anything it does not already say. + *

+ *

+ * The counter is a {@link LongAdder} rather than an {@link java.util.concurrent.atomic.AtomicLong} + * because sixteen threads incrementing one atomic would be a second contention point sitting inside + * the one under measurement. Even striped it is not free, and it is not pretended to be: it is only + * present in the scenario that also burns two microseconds per call, where it is several orders of + * magnitude below the noise it is measured against. The scenarios without a handler touch it not at + * all. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ + private static final class BurnHandler implements BlockHandler { + + /** + * The key this handler is known by. + */ + private static final Key KEY = Key.key("falco", "benchmark_burn"); + + /** + * How often {@link #onPlace(Placement)} has run. + */ + private final LongAdder placements = new LongAdder(); + + @Override + public void onPlace(Placement placement) { + this.placements.increment(); + Blackhole.consumeCPU(BURN_TOKENS); + } + + @Override + public Key getKey() { + return KEY; + } + + /** + * Returns how often this handler has been called for a placement. + * + * @return the amount of placements this handler has seen + */ + long placements() { + return this.placements.sum(); + } + } +} diff --git a/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/support/MinestomChunks.java b/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/support/MinestomChunks.java new file mode 100644 index 0000000..bbe4cd1 --- /dev/null +++ b/falco-benchmarks/src/jmh/java/net/onelitefeather/falco/benchmark/support/MinestomChunks.java @@ -0,0 +1,1067 @@ +package net.onelitefeather.falco.benchmark.support; + +import net.minestom.server.MinecraftServer; +import net.minestom.server.ServerProcess; +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.ChunkLoader; +import net.minestom.server.instance.Instance; +import net.minestom.server.instance.InstanceContainer; +import net.minestom.server.instance.InstanceManager; +import net.minestom.server.instance.block.Block; +import net.minestom.server.instance.heightmap.Heightmap; +import net.minestom.server.registry.RegistryKey; +import net.minestom.server.world.DimensionType; +import net.onelitefeather.falco.instance.FalcoChunk; +import net.onelitefeather.falco.instance.FalcoInstance; +import org.jetbrains.annotations.Nullable; + +import java.util.ArrayList; +import java.util.BitSet; +import java.util.Comparator; +import java.util.List; +import java.util.Objects; +import java.util.Random; +import java.util.UUID; + +/** + * The {@link MinestomChunks} class builds the world every chunk benchmark of this module measures on, + * and it is the single place that starts a Minestom server to do so. + *

+ * Seven benchmarks compare a chunk of Minestom against a chunk of Falco. All seven need the same four + * things: a running server process, because a chunk cannot be constructed without a dimension and a + * block registry; two instances whose configuration differs in nothing but the type under test; a + * chunk content that is reproducible to the block; and a proof that the two sides really do hold the + * same content before a single number is taken. Every one of those four is a place where a comparison + * quietly stops comparing, so all four live here rather than in seven copies. + *

+ * + *

Why the server start is centralised

+ *

+ * The block {@code if (MinecraftServer.process() == null) MinecraftServer.init();} sits copied in four + * benchmark classes of this module today. It is not thread safe: two {@code @Setup} methods can both + * read {@code null} and both call {@code init()}, and the second call replaces the {@code ServerProcess} + * of the first, which quietly detaches every instance and every registry the first one handed out. JMH + * runs a trial setup per worker thread, so the case is reachable rather than theoretical. + * {@link #ensureServer()} moves the decision into a class initialiser, where the JVM guarantees that + * the body runs exactly once and that every other thread waits for it, and hands the process back so a + * caller can assert on the one it got. + *

+ * + *

Why the two instances are built side by side

+ *

+ * {@link #newContainer()} and {@link #newFalcoInstance()} differ in one line: the class they construct. + * Same dimension, same loader, same generator, same auto chunk load, same registration with the + * {@link InstanceManager}. The chunk supplier is left at the default of each type, because that default + * is the subject of the comparison: {@code DynamicChunk} against {@code FalcoChunk}. Everything else is + * held equal on purpose — an instance that carries a loader on one side and not on the other produces + * two chunks whose difference has nothing to do with the type being measured. + *

+ * + *

Why the fill has a shape

+ *

+ * A palette is a compressor. What it costs, in bytes and in time, is decided by two properties of its + * input: how many distinct values it holds, and how those values are arranged in space. Only the first + * of the two is usually treated as a parameter, and a benchmark that varies it while drawing every + * block independently at random measures an input no world has ever produced. Pure per-block randomness + * gives every block a different neighbour, which is the worst case for run length, for the bit packer + * and for anything that exploits locality — a change that wins on real terrain would be reported as + * worthless, and a change that wins here would be reported as a win it never delivers. + *

+ *

+ * {@link FillShape} therefore separates the two properties. The state count stays a parameter, and the + * arrangement becomes a second one with three settings that bracket reality rather than sample it: + * {@link FillShape#UNIFORM} is the adversarial floor with no spatial structure at all, + * {@link FillShape#LAYERED} is the frictionless ceiling of perfectly stratified ground, and + * {@link FillShape#RANDOM_RUNS} sits between them. A result that holds at both ends holds for the + * worlds in between; a result that only holds at one end has to say which. + *

+ *

+ * {@link FillShape#RANDOM_RUNS} is the shape that models real terrain, and it does so because terrain + * is autocorrelated: a stone block is overwhelmingly likely to be next to another stone block, and the + * material changes at strata and at cave walls, not at every step. Writing runs of one block along the + * axis the storage is laid out on reproduces exactly that autocorrelation while keeping the number of + * distinct states under the control of the caller, which is what makes it comparable to the other two + * shapes at the same state count. + *

+ * + *

Why the fixture refuses to hand out air

+ *

+ * The most common silent failure in this class of measurement is a benchmark that ends up measuring an + * empty chunk. An empty palette in Minestom has {@code bitsPerEntry == 0} and no backing array at all, + * so every access degenerates into returning a single field, every save writes nothing and every + * footprint collapses to object headers. The numbers look excellent and describe nothing. A fill that + * silently did not take — wrong Y range, a chunk from a dimension with a different section count, a + * shape that wrote outside the bounds — produces precisely that, and produces it without an error. + * {@link #fill(Chunk, int, FillShape)} therefore ends in {@link #assertNotAllAir(Chunk)} and throws + * rather than returns. + *

+ * + *

Why equality is proved before the first measurement

+ *

+ * This module holds a comparison worthless unless it first shows that both sides produce the same + * result, the pattern {@code LightEngineComparisonBenchmark#verifyBothEnginesAgree} establishes. + * {@link #assertSameBlocks(Chunk, Chunk)} is that step for chunks: it walks all + * {@code 16 * 16 * 16 * sectionCount} positions plus both heightmaps and throws with the first + * disagreeing position, which aborts the trial instead of publishing a faster number for a different + * task. + *

+ * + *

Running it

+ *

+ * Nothing in this class is measured; it only builds input. It appears in two kinds of run. The JMH + * benchmarks that use it need a server, so they run under the raised heap the convention prescribes + * for that case: + *

+ * 
{@code
+ * ./gradlew :falco-benchmarks:jmhJar
+ * java -jar falco-benchmarks/build/libs/falco-benchmarks-*-jmh.jar "Chunk.*Benchmark" \
+ *     -f 1 -wi 5 -i 5 -prof gc -jvmArgs "-Xms2g -Xmx2g"
+ * }
+ *

+ * The JOL footprint tests that use it run as ordinary tests, where the build already passes the two + * flags JOL needs: + *

+ * 
{@code
+ * ./gradlew :falco-benchmarks:test --tests "*ChunkFootprintTest"
+ * ./gradlew :falco-benchmarks:test --tests "*ChunkFootprintTest" -Pfalco.compactHeaders
+ * }
+ * + * @author TheMeinerLP + * @version 1.1.0 + * @since 0.4.0 + */ +public final class MinestomChunks { + + /** + * The dimension both instances are created in. + *

+ * The overworld is the only dimension whose section count matches the + * {@link BenchmarkConstants#OVERWORLD_SECTIONS} the estimates of this module are written against, + * and it is the dimension the numbers are meant to describe. + *

+ */ + public static final RegistryKey DIMENSION = DimensionType.OVERWORLD; + + /** + * The shortest run {@link FillShape#RANDOM_RUNS} writes. + */ + public static final int RUN_LENGTH_MIN = 1; + + /** + * The longest run {@link FillShape#RANDOM_RUNS} writes. + *

+ * One row of a section along the X axis. A longer maximum would let a single draw cover several + * rows and turn the shape into a coarser {@link FillShape#LAYERED}, which is already measured + * separately; a shorter one would never produce a homogeneous row, which real ground does all the + * time. + *

+ */ + public static final int RUN_LENGTH_MAX = Chunk.CHUNK_SIZE_X; + + /** + * The amount of blocks a single section holds along one horizontal axis. + */ + private static final int SECTION_SIZE = Chunk.CHUNK_SECTION_SIZE; + + /** + * The arrangement of the block states a fill spreads over a chunk. + *

+ * All three shapes draw from the same set of states, which + * {@link MinestomChunks#distinctBlocks(int)} supplies, and all three write through + * {@link Chunk#setBlock(int, int, int, Block)} in the same order. They differ in nothing but where + * a state ends up, which is what makes a pair of runs at the same state count a measurement of the + * arrangement alone. + *

+ */ + public enum FillShape { + + /** + * The states are spread evenly over the chunk, one state per block, cycling in storage order. + *

+ * The name says uniformly distributed, not homogeneous: with {@code distinctStates == 1} every + * block is the same, and with more than one no two neighbours along the X axis are. This is the + * adversarial floor. There is no run longer than a single block, the palette reaches its full + * size in every section, and nothing that exploits spatial locality can win here. Every state + * of the set is guaranteed to appear as long as the set is smaller than the chunk. + *

+ */ + UNIFORM, + + /** + * Every horizontal layer of the chunk holds a single state, cycling from the bottom upwards. + *

+ * This is the frictionless ceiling and the shape sedimentary ground actually has: bedrock, + * deepslate, stone, dirt, grass. Each layer is one uninterrupted run of {@code 256} blocks, and + * a section sees at most {@code 16} of the states no matter how large the set is. A benchmark + * that only ran this shape would overstate every optimisation that depends on homogeneity, + * which is why it is never run alone. + *

+ */ + LAYERED, + + /** + * The chunk is written as a sequence of runs of one state, of a seeded random length between + * {@link MinestomChunks#RUN_LENGTH_MIN} and {@link MinestomChunks#RUN_LENGTH_MAX}. + *

+ * This is the shape closest to real terrain, and the reason is autocorrelation rather than + * randomness. Ground changes material at strata and at cave walls, not at every block, so the + * dominant property of a real section is that a block equals its neighbour. Pure per-block + * randomness destroys exactly that property and produces an input distribution that no world + * generator has ever emitted, while still looking like a fair test. + *

+ *

+ * The first runs are primed with the states of the set in order, so a chunk filled with this + * shape holds every state that was asked for rather than however many the draw happened to hit. + * Without that priming the state count would stop being a controlled axis and start being a + * random variable, and two shapes at the nominal same count would no longer be comparable. + *

+ */ + RANDOM_RUNS + } + + /** + * Blocks the creation of an instance because the class only builds fixtures. + */ + private MinestomChunks() { + } + + /** + * Starts the Minestom server process once and returns it. + *

+ * Idempotent and safe to call from several threads at once. The work sits in the initialiser of a + * holder class, so the JVM performs it exactly once under its own class initialisation lock and + * every further caller reads a finished field. An existing process is adopted rather than replaced, + * so a benchmark that starts the server itself before reaching this method still gets the process + * it created. + *

+ * + * @return the running server process + */ + public static ServerProcess ensureServer() { + return Server.PROCESS; + } + + /** + * Creates and registers an {@link InstanceContainer} with the configuration of this fixture. + * + * @return the created container + */ + public static InstanceContainer newContainer() { + return newContainer(ChunkLoader.noop()); + } + + /** + * Creates and registers an {@link InstanceContainer} with the configuration of this fixture. + *

+ * The container is built with the explicit five argument constructor rather than through + * {@link InstanceManager#createInstanceContainer()} so that it takes the same arguments in the same + * order as {@link #newFalcoInstance(ChunkLoader)}, and so that the loader is stated on both sides + * rather than defaulted on one of them. + *

+ * + * @param loader the loader chunks are read from and written to + * @return the created container + */ + public static InstanceContainer newContainer(ChunkLoader loader) { + final ServerProcess process = ensureServer(); + final InstanceContainer container = new InstanceContainer( + process, UUID.randomUUID(), DIMENSION, loader, DIMENSION.key()); + container.enableAutoChunkLoad(true); + process.instance().registerInstance(container); + return container; + } + + /** + * Creates and registers a {@link FalcoInstance} with the configuration of this fixture. + * + * @return the created instance + */ + public static FalcoInstance newFalcoInstance() { + return newFalcoInstance(ChunkLoader.noop()); + } + + /** + * Creates and registers a {@link FalcoInstance} with the configuration of this fixture. + *

+ * Every argument matches {@link #newContainer(ChunkLoader)}. What is deliberately not matched is + * the chunk supplier: both types keep their own default, because the difference between those two + * defaults is the thing under measurement. + *

+ * + * @param loader the loader chunks are read from and written to + * @return the created instance + */ + public static FalcoInstance newFalcoInstance(ChunkLoader loader) { + final ServerProcess process = ensureServer(); + final FalcoInstance instance = new FalcoInstance( + process, UUID.randomUUID(), DIMENSION, loader, DIMENSION.key()); + instance.enableAutoChunkLoad(true); + process.instance().registerInstance(instance); + return instance; + } + + /** + * Unregisters an instance this fixture created and unloads the chunks it holds. + *

+ * A trial that leaves its instances registered leaks them into every following trial of the same + * fork, because the {@link InstanceManager} keeps them alive and their chunks with them. That turns + * a footprint measurement into a measurement of how many trials ran before it. + * {@code InstanceManager#unregisterInstance} only unloads chunks for an {@link InstanceContainer}, + * so a {@link FalcoInstance} is released through its own {@code unregister} instead, which is the + * method that exists for exactly this gap. + *

+ * + * @param instance the instance to release, null is ignored + */ + public static void release(@Nullable Instance instance) { + if (instance == null) { + return; + } + final InstanceManager manager = ensureServer().instance(); + + if (instance instanceof FalcoInstance falcoInstance) { + falcoInstance.unregister(manager); + return; + } + if (instance.isRegistered()) { + manager.unregisterInstance(instance); + } + } + + /** + * Creates a chunk through the supplier of an instance without handing it to that instance. + *

+ * This is the chunk a footprint measurement wants: it exists, it is complete, and nothing else + * holds a reference to it, so the retained size JOL reports belongs to the chunk rather than to the + * world around it. A chunk obtained through {@link #loadChunk(Instance, int, int)} is reachable + * from the chunk map, the tick dispatcher and the entity tracker, and measuring it measures those + * too. + *

+ * + * @param instance the instance the chunk is built for + * @param chunkX the chunk X + * @param chunkZ the chunk Z + * @return the created chunk, not registered with the instance + */ + public static Chunk newChunk(Instance instance, int chunkX, int chunkZ) { + return instance.getChunkSupplier().createChunk(instance, chunkX, chunkZ); + } + + /** + * Loads a chunk into an instance and waits for it. + * + * @param instance the instance to load the chunk into + * @param chunkX the chunk X + * @param chunkZ the chunk Z + * @return the loaded chunk + */ + public static Chunk loadChunk(Instance instance, int chunkX, int chunkZ) { + return instance.loadChunk(chunkX, chunkZ).join(); + } + + /** + * Returns how many distinct usable blocks the registry holds. + *

+ * The number a benchmark has to compare its state count against before it claims that its input + * held that many different blocks. Above it, {@link #distinctBlocks(int)} keeps delivering + * distinct state ids but stops delivering distinct blocks, and the difference matters enough to be + * readable at runtime rather than only in this javadoc. On the pinned Minestom build the number is + * {@code 964}, which is below the {@code 1024} the largest planned state count asks for. + *

+ * + * @return the amount of registered blocks which are neither air nor a block entity + */ + public static int availableBlocks() { + return BlockSet.BLOCKS.length; + } + + /** + * Returns how many distinct block states this fixture can draw from in total. + * + * @return the amount of usable block states, distinct blocks and their further states together + */ + public static int availableStates() { + return BlockSet.BLOCKS.length + ExtraStates.STATES.length; + } + + /** + * Returns the requested amount of distinct block states, distinct blocks first. + *

+ * Distinct blocks before distinct states of one block, and that order is the point of the + * method. A palette does not care which state ids it holds, but everything around it does: taking + * two hundred states of stone would give two hundred ids sitting next to each other in the + * registry, all with the same handler, the same occlusion and the same behaviour in every heightmap + * and light computation. That is neither what a world looks like nor what the code paths around the + * palette meet in production, and a palette benchmark fed that way would report on an input whose + * only realistic property is its cardinality. + *

+ *

+ * Two kinds of block are excluded. Air is excluded because a fixture whose job is to prevent an + * accidentally empty chunk must not put emptiness into the set in the first place. Block entities + * are excluded because Minestom does not keep them in the palette at all: {@code DynamicChunk} + * stores them in a side map keyed by block index, so a chunk filled with chests would measure a + * hash map with {@code 98304} entries instead of the storage under test, and would do so while + * looking like a legitimate fill. + *

+ *

+ * Those two exclusions leave fewer distinct blocks than the largest planned state count asks for — + * {@code 964} against {@code 1024} on the pinned build. Rather than cap the axis, the set falls + * back to the remaining states of the same blocks once the distinct ones run out, again by + * ascending state id. The fallback is stated here and readable through {@link #availableBlocks()} + * rather than hidden, because a measurement above that boundary is answering a slightly different + * question than one below it, and the two halves of such a curve must not be read as one. + *

+ * + * @param wanted the amount of distinct block states to return + * @return the blocks, in a stable order across runs + * @throws IllegalArgumentException if {@code wanted} is smaller than one + * @throws IllegalStateException if the registry holds fewer usable states than requested + */ + public static Block[] distinctBlocks(int wanted) { + if (wanted < 1) { + throw new IllegalArgumentException("A fill needs at least one block state, got " + wanted); + } + final Block[] blocks = BlockSet.BLOCKS; + + if (wanted <= blocks.length) { + final Block[] result = new Block[wanted]; + System.arraycopy(blocks, 0, result, 0, wanted); + return result; + } + final Block[] extras = ExtraStates.STATES; + final int missing = wanted - blocks.length; + + if (missing > extras.length) { + throw new IllegalStateException("The block registry holds " + blocks.length + " blocks and " + + extras.length + " further states which are neither air nor a block entity, so " + + wanted + " distinct states cannot be built"); + } + final Block[] result = new Block[wanted]; + System.arraycopy(blocks, 0, result, 0, blocks.length); + System.arraycopy(extras, 0, result, blocks.length, missing); + return result; + } + + /** + * Returns the state ids of {@link #distinctBlocks(int)}. + *

+ * For the benchmarks that write into a {@code Palette} directly rather than through a chunk. + *

+ * + * @param wanted the amount of distinct states to return + * @return the state ids, in a stable order across runs + * @throws IllegalArgumentException if {@code wanted} is smaller than one + * @throws IllegalStateException if the registry holds fewer usable blocks than requested + */ + public static int[] distinctStates(int wanted) { + final Block[] blocks = distinctBlocks(wanted); + final int[] states = new int[blocks.length]; + + for (int index = 0; index < blocks.length; index++) { + states[index] = blocks[index].stateId(); + } + return states; + } + + /** + * Fills a chunk with the given amount of distinct block states in the given arrangement, using the + * seed of this module. + * + * @param chunk the chunk to fill + * @param distinctStates the amount of distinct block states the fill draws from + * @param shape the arrangement the states are written in + * @throws IllegalArgumentException if the state count does not fit the chunk + * @throws IllegalStateException if the chunk holds nothing but air afterwards + */ + public static void fill(Chunk chunk, int distinctStates, FillShape shape) { + fill(chunk, distinctStates, shape, BenchmarkConstants.SEED); + } + + /** + * Fills a chunk with the given amount of distinct block states in the given arrangement. + *

+ * The write order is Y outermost and X innermost, ascending, and that is not an implementation + * detail. Ascending Y is what keeps the heightmap refresh on its cheap branch: a block that raises + * the column only compares and stores, while a block written below the current height sends the + * heightmap back down the column with a palette scan per step. A fill that ran top down would spend + * most of its time in a code path that a real world reaches when a player mines, not when a chunk + * is generated, and would make the setup of the benchmark dominate the benchmark. + *

+ *

+ * The fill goes through {@link Chunk#setBlock(int, int, int, Block)} rather than writing into the + * palettes of the sections behind it. Writing into the palettes is faster and is what some existing + * benchmarks of this module do, but it leaves the heightmaps, the block entity map and the packet + * cache in a state no sequence of public calls could produce, and it assumes that every chunk under + * test stores its blocks in Minestom sections at all — which is exactly the assumption a Falco + * chunk with its own storage would break. The public setter is the only path both sides are + * guaranteed to share. + *

+ * + * @param chunk the chunk to fill + * @param distinctStates the amount of distinct block states the fill draws from + * @param shape the arrangement the states are written in + * @param seed the seed {@link FillShape#RANDOM_RUNS} draws its runs from + * @throws IllegalArgumentException if the state count does not fit the chunk + * @throws IllegalStateException if the chunk holds nothing but air afterwards + */ + public static void fill(Chunk chunk, int distinctStates, FillShape shape, long seed) { + final int minY = chunk.getMinSection() * SECTION_SIZE; + final int maxY = chunk.getMaxSection() * SECTION_SIZE; + final int positions = blockCount(chunk); + + if (distinctStates > positions) { + throw new IllegalArgumentException("The chunk holds " + positions + " blocks and cannot show " + + distinctStates + " distinct states"); + } + final Block[] blocks = distinctBlocks(distinctStates); + + chunk.lockWriteLock(); + try { + switch (shape) { + case UNIFORM -> fillUniform(chunk, blocks, minY, maxY); + case LAYERED -> fillLayered(chunk, blocks, minY, maxY); + case RANDOM_RUNS -> fillRandomRuns(chunk, blocks, minY, maxY, seed); + } + } finally { + chunk.unlockWriteLock(); + } + assertNotAllAir(chunk); + } + + /** + * Returns the amount of block positions a chunk holds. + * + * @param chunk the chunk to measure + * @return {@code 16 * 16 * 16} times the section count of the chunk + */ + public static int blockCount(Chunk chunk) { + return BenchmarkConstants.BLOCK_ENTRIES * (chunk.getMaxSection() - chunk.getMinSection()); + } + + /** + * Verifies that a chunk holds at least one block which is not air. + *

+ * The check that stops the most common silent failure of this module. An all air chunk answers + * every read from a palette with {@code bitsPerEntry == 0} and no backing array, saves to almost + * nothing and weighs almost nothing, so a benchmark that lost its fill reports the best numbers it + * will ever produce and reports them for an empty world. The check stops at the first block it + * finds, so it costs a single read on a chunk that is fine. + *

+ * + * @param chunk the chunk to check + * @throws IllegalStateException if every block of the chunk is air + */ + public static void assertNotAllAir(Chunk chunk) { + final int minY = chunk.getMinSection() * SECTION_SIZE; + final int maxY = chunk.getMaxSection() * SECTION_SIZE; + + chunk.lockReadLock(); + try { + for (int y = minY; y < maxY; y++) { + for (int z = 0; z < Chunk.CHUNK_SIZE_Z; z++) { + for (int x = 0; x < Chunk.CHUNK_SIZE_X; x++) { + if (!typeAt(chunk, x, y, z).isAir()) { + return; + } + } + } + } + } finally { + chunk.unlockReadLock(); + } + throw new IllegalStateException("The chunk " + chunk.getChunkX() + ":" + chunk.getChunkZ() + + " holds nothing but air over all " + blockCount(chunk) + + " positions, so a measurement on it would measure an empty palette"); + } + + /** + * Counts the blocks of a chunk which are not air. + * + * @param chunk the chunk to count in + * @return the amount of non air blocks + */ + public static int countNonAir(Chunk chunk) { + final int minY = chunk.getMinSection() * SECTION_SIZE; + final int maxY = chunk.getMaxSection() * SECTION_SIZE; + int found = 0; + + chunk.lockReadLock(); + try { + for (int y = minY; y < maxY; y++) { + for (int z = 0; z < Chunk.CHUNK_SIZE_Z; z++) { + for (int x = 0; x < Chunk.CHUNK_SIZE_X; x++) { + if (!typeAt(chunk, x, y, z).isAir()) { + found++; + } + } + } + } + } finally { + chunk.unlockReadLock(); + } + return found; + } + + /** + * Counts how many distinct block states a chunk actually holds. + *

+ * The second half of the anti tautology check, and the one a parametrised benchmark needs: the + * state count is an axis of the measurement, so a run has to be able to show that the axis was + * really set. {@link FillShape#LAYERED} in particular cannot reach more than {@code 16} states per + * section, and a benchmark that reports a curve over {@code 1024} states while every point of it + * held {@code 384} would be describing a chunk it never built. + *

+ * + * @param chunk the chunk to count in + * @return the amount of distinct block state ids, air included + */ + public static int countDistinctStates(Chunk chunk) { + final int minY = chunk.getMinSection() * SECTION_SIZE; + final int maxY = chunk.getMaxSection() * SECTION_SIZE; + final BitSet seen = new BitSet(); + + chunk.lockReadLock(); + try { + for (int y = minY; y < maxY; y++) { + for (int z = 0; z < Chunk.CHUNK_SIZE_Z; z++) { + for (int x = 0; x < Chunk.CHUNK_SIZE_X; x++) { + seen.set(typeAt(chunk, x, y, z).stateId()); + } + } + } + } finally { + chunk.unlockReadLock(); + } + return seen.cardinality(); + } + + /** + * Verifies that two chunks hold the same block at every position and the same heightmaps. + *

+ * This is the equivalence stage a comparison benchmark of this module has to pass before its first + * measurement, in the shape {@code LightEngineComparisonBenchmark#verifyBothEnginesAgree} + * established: it throws, so a trial that would have compared two different worlds stops instead of + * publishing a number. + *

+ *

+ * The walk reads with {@link Block.Getter.Condition#NONE} rather than + * {@link Block.Getter.Condition#TYPE}, which is the stricter of the two. {@code TYPE} answers from + * the palette alone and would accept two chunks that store the same state ids but disagree about + * which of them carry nbt or a handler; {@code NONE} consults the block entity map first and falls + * back to the palette, so one walk covers both places a chunk keeps block data, and + * {@code Block#equals} compares the state id, the nbt and the handler. + *

+ *

+ * Both heightmaps are compared afterwards, per column rather than through their packed form, + * because a difference in a packed long says only that something is wrong while a difference in a + * column says where. They are not redundant with the block walk: a heightmap is derived state that + * is maintained incrementally on every write, so two chunks can hold identical blocks and still + * disagree about their heights if one of them refreshed differently — and the heightmap is what + * ends up in the chunk packet. + *

+ * + *

Why this check may not touch {@code Chunk#getSections()}

+ *

+ * It used to compare {@code expected.getSections().size()} against {@code actual.getSections().size()}, + * and on a {@link net.onelitefeather.falco.instance.FalcoChunk} that one line was not a read. Its + * storage hands out a real {@code Section} per slot there, so asking for the list materialised all + * twenty-four of a chunk that held none — which turned every footprint number taken after this + * check into a measurement of the check. Measured: a fresh {@code FalcoChunk} retains {@code 32} + * objects, and {@code 193} once this method has run over it, against {@code 192} for the + * {@code DynamicChunk} it is compared with. The section count is therefore read through + * {@link #sectionCount(Chunk)}, which asks a Falco chunk's storage instead of its section list. + *

+ *

+ * The heightmaps are the second such place and cannot be sidestepped, only started correctly. + * {@code Heightmap#getHeight} refreshes on first use and begins that refresh at + * {@code Heightmap#getHighestBlockSection(Chunk)}, which walks every section from the build limit + * downwards through {@code Chunk#getSection(int)} — twenty-four materialisations before the scan + * proper has begun. {@link #primeHeightmaps(Chunk)} starts both heightmaps of each side from that + * side's own scan, the way {@code ChunkComparisonBenchmark} already starts them, so the descent + * begins at the height the chunk itself reports. What the descent then materialises is the + * documented cost of {@code Heightmap#refresh(int, int, int)} and is asserted per fixture in + * {@code SectionMaterialisationTest}; it is not this method's to hide. + *

+ * + * @param expected the chunk that defines the content, usually the Minestom side + * @param actual the chunk that has to match it, usually the Falco side + * @throws IllegalStateException if the two chunks differ in their bounds, in a block or in a height + */ + public static void assertSameBlocks(Chunk expected, Chunk actual) { + if (expected.getMinSection() != actual.getMinSection() || expected.getMaxSection() != actual.getMaxSection()) { + throw new IllegalStateException("The chunks span different sections: expected [" + + expected.getMinSection() + ", " + expected.getMaxSection() + ") but got [" + + actual.getMinSection() + ", " + actual.getMaxSection() + ")"); + } + if (sectionCount(expected) != sectionCount(actual)) { + throw new IllegalStateException("The chunks hold a different amount of sections: expected " + + sectionCount(expected) + " but got " + sectionCount(actual)); + } + final int minY = expected.getMinSection() * SECTION_SIZE; + final int maxY = expected.getMaxSection() * SECTION_SIZE; + + expected.lockReadLock(); + try { + actual.lockReadLock(); + try { + compareBlocks(expected, actual, minY, maxY); + primeHeightmaps(expected); + primeHeightmaps(actual); + compareHeightmaps(expected, actual, expected.motionBlockingHeightmap(), actual.motionBlockingHeightmap()); + compareHeightmaps(expected, actual, expected.worldSurfaceHeightmap(), actual.worldSurfaceHeightmap()); + } finally { + actual.unlockReadLock(); + } + } finally { + expected.unlockReadLock(); + } + } + + /** + * Reports how many sections a chunk spans without making it create any. + *

+ * {@code Chunk} declares no such accessor, and the only one it has, + * {@code Chunk#getSections()}, is a write on every lazy layout. A + * {@link net.onelitefeather.falco.instance.FalcoChunk} is asked through its storage, which knows + * its own length; every other chunk answers from its section list, where the question is free. + *

+ * + * @param chunk the chunk to count the sections of + * @return the amount of sections the chunk spans + */ + public static int sectionCount(Chunk chunk) { + if (chunk instanceof FalcoChunk falcoChunk) { + return falcoChunk.storage().sectionCount(); + } + return chunk.getSections().size(); + } + + /** + * Computes both heightmaps of a chunk from the scan that chunk starts them with. + *

+ * A no-op for a heightmap that has already been refreshed, because {@code Heightmap#refresh(int)} + * returns on its own {@code needsRefresh}. For one that has not, it decides where the column + * descent begins: {@code FalcoChunk#highestBlockSection()} finds the top of the terrain through + * the read-only view of its storage, while {@code Heightmap#getHighestBlockSection(Chunk)} finds + * the same height through {@code Chunk#getSection(int)}. The two answer identically — that is + * covered by {@code FalcoChunkEquivalenceTest} — but only the first one is a read. + *

+ * + * @param chunk the chunk whose heightmaps are computed + */ + public static void primeHeightmaps(Chunk chunk) { + final int startY = chunk instanceof FalcoChunk falcoChunk + ? falcoChunk.highestBlockSection() + : Heightmap.getHighestBlockSection(chunk); + + chunk.motionBlockingHeightmap().refresh(startY); + chunk.worldSurfaceHeightmap().refresh(startY); + } + + /** + * Writes one state per block, cycling through the set in storage order. + * + * @param chunk the chunk to fill + * @param blocks the states to spread + * @param minY the lowest block Y of the chunk + * @param maxY the block Y one above the highest one of the chunk + */ + private static void fillUniform(Chunk chunk, Block[] blocks, int minY, int maxY) { + int index = 0; + + for (int y = minY; y < maxY; y++) { + for (int z = 0; z < Chunk.CHUNK_SIZE_Z; z++) { + for (int x = 0; x < Chunk.CHUNK_SIZE_X; x++) { + chunk.setBlock(x, y, z, blocks[index % blocks.length]); + index++; + } + } + } + } + + /** + * Writes one state per horizontal layer, cycling through the set from the bottom upwards. + * + * @param chunk the chunk to fill + * @param blocks the states to spread + * @param minY the lowest block Y of the chunk + * @param maxY the block Y one above the highest one of the chunk + */ + private static void fillLayered(Chunk chunk, Block[] blocks, int minY, int maxY) { + for (int y = minY; y < maxY; y++) { + final Block block = blocks[(y - minY) % blocks.length]; + + for (int z = 0; z < Chunk.CHUNK_SIZE_Z; z++) { + for (int x = 0; x < Chunk.CHUNK_SIZE_X; x++) { + chunk.setBlock(x, y, z, block); + } + } + } + } + + /** + * Writes runs of one state along the storage order, of a seeded random length. + *

+ * The first runs are primed with the states of the set in order so that the chunk is guaranteed to + * hold every state that was requested. Only after the set is exhausted does the state of a run + * become a draw. + *

+ * + * @param chunk the chunk to fill + * @param blocks the states to spread + * @param minY the lowest block Y of the chunk + * @param maxY the block Y one above the highest one of the chunk + * @param seed the seed the run lengths and the states are drawn from + */ + private static void fillRandomRuns(Chunk chunk, Block[] blocks, int minY, int maxY, long seed) { + final Random random = new Random(seed); + final int span = RUN_LENGTH_MAX - RUN_LENGTH_MIN + 1; + Block current = blocks[0]; + int remaining = 0; + int primed = 0; + + for (int y = minY; y < maxY; y++) { + for (int z = 0; z < Chunk.CHUNK_SIZE_Z; z++) { + for (int x = 0; x < Chunk.CHUNK_SIZE_X; x++) { + if (remaining == 0) { + current = primed < blocks.length ? blocks[primed++] : blocks[random.nextInt(blocks.length)]; + remaining = RUN_LENGTH_MIN + random.nextInt(span); + } + chunk.setBlock(x, y, z, current); + remaining--; + } + } + } + } + + /** + * Compares every block of two chunks and throws at the first difference. + * + * @param expected the chunk that defines the content + * @param actual the chunk that has to match it + * @param minY the lowest block Y of both chunks + * @param maxY the block Y one above the highest one of both chunks + * @throws IllegalStateException if the two chunks hold a different block anywhere + */ + private static void compareBlocks(Chunk expected, Chunk actual, int minY, int maxY) { + for (int y = minY; y < maxY; y++) { + for (int z = 0; z < Chunk.CHUNK_SIZE_Z; z++) { + for (int x = 0; x < Chunk.CHUNK_SIZE_X; x++) { + final Block expectedBlock = expected.getBlock(x, y, z, Block.Getter.Condition.NONE); + final Block actualBlock = actual.getBlock(x, y, z, Block.Getter.Condition.NONE); + + if (Objects.equals(expectedBlock, actualBlock)) { + continue; + } + throw new IllegalStateException("The chunks disagree at x=" + x + " y=" + y + " z=" + z + + ": " + describe(expected) + " holds " + describe(expectedBlock) + " but " + + describe(actual) + " holds " + describe(actualBlock)); + } + } + } + } + + /** + * Compares two heightmaps column by column and throws at the first difference. + * + * @param expectedChunk the chunk the expected heightmap belongs to + * @param actualChunk the chunk the actual heightmap belongs to + * @param expected the heightmap that defines the heights + * @param actual the heightmap that has to match it + * @throws IllegalStateException if the two heightmaps hold a different height anywhere + */ + private static void compareHeightmaps(Chunk expectedChunk, Chunk actualChunk, + Heightmap expected, Heightmap actual) { + if (expected.type() != actual.type()) { + throw new IllegalStateException("The chunks compare heightmaps of different types: " + + expected.type() + " against " + actual.type()); + } + for (int z = 0; z < Chunk.CHUNK_SIZE_Z; z++) { + for (int x = 0; x < Chunk.CHUNK_SIZE_X; x++) { + final int expectedHeight = expected.getHeight(x, z); + final int actualHeight = actual.getHeight(x, z); + + if (expectedHeight == actualHeight) { + continue; + } + throw new IllegalStateException("The chunks disagree on the " + expected.type() + + " height of the column x=" + x + " z=" + z + ": " + describe(expectedChunk) + + " holds " + expectedHeight + " but " + describe(actualChunk) + " holds " + actualHeight); + } + } + } + + /** + * Reads the block type at a position of a chunk, treating an absent answer as air. + *

+ * {@link Block.Getter#getBlock(int, int, int, Block.Getter.Condition)} is declared with unknown + * nullability because {@link Block.Getter.Condition#CACHED} is allowed to answer with nothing. The + * counters of this class never ask for that condition, but they run against chunk implementations + * this module is written to compare rather than against one it controls, so the fallback is stated + * instead of assumed. + *

+ * + * @param chunk the chunk to read from, with the read lock held by the caller + * @param x the block X inside the chunk + * @param y the block Y + * @param z the block Z inside the chunk + * @return the block at the position, air if the chunk answered with nothing + */ + private static Block typeAt(Chunk chunk, int x, int y, int z) { + return Objects.requireNonNullElse(chunk.getBlock(x, y, z, Block.Getter.Condition.TYPE), Block.AIR); + } + + /** + * Names a chunk by its type and position for a failure message. + * + * @param chunk the chunk to name + * @return the name of the chunk + */ + private static String describe(Chunk chunk) { + return chunk.getClass().getSimpleName() + "[" + chunk.getChunkX() + ":" + chunk.getChunkZ() + "]"; + } + + /** + * Names a block by its key and state id for a failure message. + * + * @param block the block to name, null if the chunk answered with nothing + * @return the name of the block + */ + private static String describe(@Nullable Block block) { + if (block == null) { + return "nothing"; + } + return block.key().asString() + "(" + block.stateId() + ")"; + } + + /** + * Holds the server process so it is started exactly once. + *

+ * A holder class rather than a synchronised method or a double checked field: class initialisation + * is the one mechanism the JVM already performs under a lock, exactly once, with the result + * published safely to every thread that reads the field afterwards. It costs nothing on the reads + * that follow. + *

+ */ + private static final class Server { + + /** + * The running server process, adopted if one already exists. + */ + static final ServerProcess PROCESS = start(); + + /** + * Blocks the creation of an instance because the class only holds the process. + */ + private Server() { + } + + /** + * Returns the running server process, starting one if there is none. + * + * @return the running server process + */ + private static ServerProcess start() { + final ServerProcess running = MinecraftServer.process(); + + if (running != null) { + return running; + } + MinecraftServer.init(); + return MinecraftServer.process(); + } + } + + /** + * Holds the blocks a fill draws from so the registry is walked exactly once. + */ + private static final class BlockSet { + + /** + * Every registered block which is neither air nor a block entity, by ascending state id. + */ + static final Block[] BLOCKS = collect(); + + /** + * Blocks the creation of an instance because the class only holds the blocks. + */ + private BlockSet() { + } + + /** + * Walks the block registry and collects the blocks a fill may use. + *

+ * The result is sorted by state id rather than left in registry order, because the registry is + * backed by a hash map whose iteration order is an implementation detail. Sorting makes the + * set the same on every run and on every Minestom build that keeps its ids, which is what turns + * a state count into a reproducible axis. + *

+ * + * @return the usable blocks, by ascending state id + */ + private static Block[] collect() { + ensureServer(); + final List collected = new ArrayList<>(); + + for (Block block : Block.values()) { + if (usable(block)) { + collected.add(block); + } + } + collected.sort(Comparator.comparingInt(Block::stateId)); + return collected.toArray(new Block[0]); + } + } + + /** + * Holds the further states of the usable blocks, built only when a fill asks for more distinct + * states than there are distinct blocks. + *

+ * Separate from {@link BlockSet} because walking {@code possibleStates()} of every block is far + * more work than walking the registry, and the state counts a benchmark actually runs are below + * {@link #availableBlocks()} most of the time. A holder that is never touched is never initialised. + *

+ */ + private static final class ExtraStates { + + /** + * Every state of a usable block except the default one, by ascending state id. + */ + static final Block[] STATES = collect(); + + /** + * Blocks the creation of an instance because the class only holds the states. + */ + private ExtraStates() { + } + + /** + * Walks the states of every usable block and collects the ones the block set does not hold. + * + * @return the further states, by ascending state id + */ + private static Block[] collect() { + final List collected = new ArrayList<>(); + + for (Block block : BlockSet.BLOCKS) { + for (Block state : block.possibleStates()) { + if (state.stateId() != block.stateId()) { + collected.add(state); + } + } + } + collected.sort(Comparator.comparingInt(Block::stateId)); + return collected.toArray(new Block[0]); + } + } + + /** + * Tells whether a block may take part in a fill. + * + * @param block the block to judge + * @return true if the block is neither air nor a block entity + */ + private static boolean usable(Block block) { + return !block.isAir() && !block.registry().isBlockEntity(); + } +} diff --git a/falco-benchmarks/src/test/java/net/minestom/server/instance/ChunkViewerCacheLeakTest.java b/falco-benchmarks/src/test/java/net/minestom/server/instance/ChunkViewerCacheLeakTest.java new file mode 100644 index 0000000..d0d21f7 --- /dev/null +++ b/falco-benchmarks/src/test/java/net/minestom/server/instance/ChunkViewerCacheLeakTest.java @@ -0,0 +1,228 @@ +package net.minestom.server.instance; + +import net.minestom.server.entity.Entity; +import net.onelitefeather.falco.benchmark.support.MinestomChunks; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Nested; +import org.junit.jupiter.api.Test; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * The {@link ChunkViewerCacheLeakTest} class establishes that constructing a chunk for an + * {@code InstanceContainer} leaves an entry in the viewer cache of its entity tracker that nothing + * ever removes, and that the same construction for a {@code FalcoInstance} does not. + * + *

Why this test exists

+ *

+ * It was written to explain a benchmark result rather than to look for a defect. + * {@code ChunkComparisonBenchmark} reported {@code FalcoChunk#copy} as twenty to forty times faster + * than {@code DynamicChunk#copy} while every other measured operation of the two agreed to the + * decimal, which cannot be true of the code: the two implementations differ only in that the Falco + * one carries over its tickable bookkeeping as well, so it does strictly more work — at the time a + * whole {@code Int2ObjectOpenHashMap} copy, today the single {@code int} that replaced it, which + * makes the argument weaker in magnitude and no different in direction. A difference of that + * size with no cause in the code means the two arms are not measuring the same thing, and the + * benchmark had to be disqualified until the cause was named. This is the cause. + *

+ * + *

The mechanism

+ *

+ * Every chunk asks the entity tracker of its instance for a {@code Viewable} while it is being + * constructed, and hands it the shared instances of that instance to key the lookup by: + *

+ * 
{@code
+ * // Chunk
+ * final List shared = instance instanceof InstanceContainer instanceContainer ?
+ *         instanceContainer.getSharedInstances() : List.of();
+ * this.viewable = instance.getEntityTracker().viewable(shared, chunkX, chunkZ);
+ *
+ * // EntityTrackerImpl
+ * return entry.viewers.computeIfAbsent(new ChunkViewKey(sharedInstances, chunkX, chunkZ), ChunkView::new);
+ *
+ * // EntityTrackerImpl.ChunkViewKey — the list is compared by identity, not by value
+ * return sharedInstances == instances && chunkX == x && chunkZ == z;
+ * }
+ *

+ * {@code InstanceContainer#getSharedInstances} returns {@code Collections.unmodifiableList(...)}, + * which is a fresh wrapper on every call. A key built from it is therefore never {@code equals} to a + * key already in the map, so {@code computeIfAbsent} inserts every single time and the map grows + * without bound. An instance that is not an {@code InstanceContainer} is handed {@code List.of()} + * instead, and because that is one shared immutable singleton the identity comparison succeeds and + * the entry is reused. + *

+ *

+ * The growth is not the whole cost. {@code ChunkViewKey} is a record that overrides {@code equals} + * and does not override {@code hashCode}, so the generated value based {@code hashCode} is still in + * force. Two empty lists hash alike, which means every leaked key of a given chunk position hashes + * into the same bin while none of them compares equal to another. The map therefore does not merely + * grow, it grows into one bin, and each insertion has to walk what is already there. + *

+ * + *

What this does and does not say

+ *

+ * It says that the leak exists, that it is linear in the amount of chunk constructions, and that + * {@code FalcoInstance} does not trigger it. What it does not say is that being bounded is a design. + * A {@code FalcoInstance} escapes the unbounded growth for the single reason that it is not an + * {@code InstanceContainer} and is therefore handed the {@code List.of()} singleton; what it does not + * escape that way is the bounded remainder, one entry per chunk position, created by the first chunk + * built there. + *

+ *

+ * That remainder is gone since {@code ChunkLifecycle#unload} gives the entry back through + * {@code ChunkViewerCache}, and the proof of it is deliberately not here. It is + * {@code ChunkViewerCacheTest#testALoadAndUnloadCycleIsNeutral} in {@code falco-instance}, which + * drives thirty-two load and unload cycles and asserts that the cache ends at the size it started + * at; removing the release from the unload path fails it by exactly thirty-two entries. + *

+ *

+ * The case cannot be repeated in this module, and the reason is a property of this test JVM rather + * than of the subject. A real load hands the chunk to {@code ThreadDispatcher#createPartition} and + * the unload to {@code deletePartition}, and both only enqueue an update which + * {@code ThreadDispatcherImpl#updateAndAwait} applies at the start of the next tick. The server this + * module starts is {@code MinecraftServer.init()} without a tick loop, so that queue is never drained + * and every chunk a test loads stays strongly reachable from the {@code ServerProcess} — which every + * instance holds a field of. {@link net.onelitefeather.falco.benchmark.instance.ChunkFootprintTest} + * measures a chunk as the difference between a walk of chunk plus instance and a walk of the instance + * alone, and states that no walk of an instance reaches the static + * {@code LazySectionBlockStorage#EMPTY} flyweight. One retained {@code FalcoChunk} makes that + * sentence false, and the fresh Falco chunk then measures zero of the six objects that flyweight + * contributes. Added here, the cycles failed that class in four of four runs where JUnit happened to + * schedule this one first and in none of four where it did not, against six of six green without + * them. + *

+ * + *

Running it

+ * 
{@code
+ * ./gradlew :falco-benchmarks:test --tests "*ChunkViewerCacheLeakTest*" -i
+ * }
+ * + * @author TheMeinerLP + * @version 1.1.0 + * @since 0.4.0 + */ +@DisplayName("The viewer cache an instance keeps for its chunks") +class ChunkViewerCacheLeakTest { + + /** + * The chunk position every constructed chunk is placed at. + *

+ * One position for all of them on purpose. A leak that is keyed by position would be + * indistinguishable from correct behaviour if every chunk sat somewhere else, because one entry + * per position is exactly what the cache is for. Holding the position still makes every entry + * after the first one a leaked entry by definition. + *

+ */ + private static final int POSITION = 0; + + /** + * The amounts of chunk constructions the growth is sampled at. + *

+ * Three points rather than one, because the claim is that the growth is linear rather than that + * it is nonzero. A single sample cannot tell an unbounded leak from a bounded overhead. + *

+ */ + private static final int[] SAMPLES = {16, 160, 1600}; + + /** + * Reads how many entries the viewer cache of an instance holds. + * + * @param instance the instance to read from + * @return the amount of cached views + */ + private static int viewerCacheSize(Instance instance) { + final EntityTrackerImpl tracker = (EntityTrackerImpl) instance.getEntityTracker(); + final EntityTrackerImpl.TargetEntry entry = + tracker.targetEntries[EntityTracker.Target.PLAYERS.ordinal()]; + + return entry.viewers.size(); + } + + /** + * Constructs the given amount of chunks at the same position and reports the growth of the cache. + * + * @param instance the instance to construct the chunks for + * @param amount the amount of chunks to construct + * @return the amount of entries the construction added to the cache + */ + private static int growthOver(Instance instance, int amount) { + final int before = viewerCacheSize(instance); + + for (int index = 0; index < amount; index++) { + final Chunk chunk = MinestomChunks.newChunk(instance, POSITION, POSITION); + + // Without this the JIT is free to drop a construction whose result is never read, and + // the test would report the absence of a leak it simply never triggered. + assertTrue(chunk.getChunkX() == POSITION, "the constructed chunk is at the sampled position"); + } + return viewerCacheSize(instance) - before; + } + + /** + * The tests that show the container leaking. + */ + @Nested + @DisplayName("for an InstanceContainer") + class ForAContainer { + + /** + * Establishes that the cache grows by one entry per construction, without bound. + */ + @Test + @DisplayName("grows by one entry per constructed chunk and never shrinks") + void testTheCacheGrowsWithEveryConstruction() { + final InstanceContainer container = MinestomChunks.newContainer(); + + try { + final StringBuilder report = new StringBuilder("viewer cache of an InstanceContainer\n"); + + for (int sample : SAMPLES) { + final int growth = growthOver(container, sample); + + report.append(String.format(" %6d constructions -> %6d new entries%n", sample, growth)); + assertEquals(sample, growth, "every construction leaks exactly one entry, so the growth " + + "equals the amount of constructions"); + } + System.out.println(report); + } finally { + MinestomChunks.release(container); + } + } + } + + /** + * The tests that show a Falco instance escaping the leak. + */ + @Nested + @DisplayName("for a FalcoInstance") + class ForAFalcoInstance { + + /** + * Establishes that repeated construction at one position adds at most the one entry the + * cache exists for. + */ + @Test + @DisplayName("holds one entry per position no matter how often a chunk is constructed") + void testTheCacheStaysBounded() { + final Instance falco = MinestomChunks.newFalcoInstance(); + + try { + final StringBuilder report = new StringBuilder("viewer cache of a FalcoInstance\n"); + int total = 0; + + for (int sample : SAMPLES) { + final int growth = growthOver(falco, sample); + + total += growth; + report.append(String.format(" %6d constructions -> %6d new entries%n", sample, growth)); + } + System.out.println(report); + assertTrue(total <= 1, "one position can need at most one cached view, but the cache grew by " + + total + " entries"); + } finally { + MinestomChunks.release(falco); + } + } + } +} diff --git a/falco-benchmarks/src/test/java/net/onelitefeather/falco/benchmark/instance/ChunkFootprintTest.java b/falco-benchmarks/src/test/java/net/onelitefeather/falco/benchmark/instance/ChunkFootprintTest.java new file mode 100644 index 0000000..cc4c866 --- /dev/null +++ b/falco-benchmarks/src/test/java/net/onelitefeather/falco/benchmark/instance/ChunkFootprintTest.java @@ -0,0 +1,1542 @@ +package net.onelitefeather.falco.benchmark.instance; + +import it.unimi.dsi.fastutil.ints.Int2ObjectOpenHashMap; +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.Instance; +import net.minestom.server.instance.InstanceContainer; +import net.minestom.server.instance.Section; +import net.onelitefeather.falco.benchmark.support.MinestomChunks; +import net.onelitefeather.falco.benchmark.support.MinestomChunks.FillShape; +import net.onelitefeather.falco.instance.FalcoInstance; +import net.onelitefeather.falco.instance.LazySectionBlockStorage; +import org.junit.jupiter.api.AfterAll; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.parallel.ResourceLock; +import org.junit.jupiter.api.parallel.Resources; +import org.openjdk.jol.info.ClassLayout; +import org.openjdk.jol.info.GraphLayout; +import org.openjdk.jol.vm.VM; + +import java.util.Comparator; +import java.util.LinkedHashSet; +import java.util.Locale; +import java.util.Map; +import java.util.Set; +import java.util.TreeMap; +import java.util.TreeSet; +import java.util.function.LongUnaryOperator; +import java.util.function.ToLongFunction; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * The {@link ChunkFootprintTest} class measures how many bytes a single chunk of Minestom really + * retains, with JOL, and prints the result as a table that can be copied into the documentation. + *

+ * It exists because every memory number this project has written down so far is an estimate. The + * research report of 2026-08-01 says so itself: its whole balance sheet — roughly one hundred and + * seventy objects per chunk, six to ten kibibytes empty, about two hundred kibibytes once a + * generator has filled it — comes from layout arithmetic over assumed object sizes, and the same + * kind of arithmetic had already put one break-even point wrong by a factor of two. This class + * replaces all of those numbers with measured ones. Nothing here is a benchmark: no time is taken, + * no warmup is needed for the subject, and the quantity of interest is bytes on the heap, which is + * exactly what {@code -prof gc} cannot tell anyone, because allocation rate is not footprint. + *

+ * + *

Why a chunk cannot simply be handed to JOL

+ *

+ * {@code GraphLayout.parseInstance(chunk).totalSize()} answers the wrong question. A chunk holds a + * reference to its {@code Instance} ({@code Chunk.java:37}), the instance holds an entity tracker, a + * scheduler, an event node and a world border, and a reachability walk that starts at the chunk + * therefore reports the weight of the world the chunk lives in. On the pinned build that is roughly + * eight hundred objects of instance against under two hundred of chunk, so the number would be + * dominated by the part nobody asked about, and it would drift with every field Minestom adds to + * {@code Instance}. + *

+ *

+ * What this class reports instead is the difference between two walks: everything reachable from the + * chunk and the instance together, minus everything reachable from the instance alone. Both + * walks deduplicate by object identity internally, so the difference is exactly the set of objects + * that exist because the chunk exists — and it is computed from two independent totals rather than + * from {@code GraphLayout#subtract}, which matches objects by their address and therefore silently + * miscounts every object the garbage collector moved between the two snapshots. + *

+ *

+ * The boundary that draws is worth stating, because it is a result in itself: anything a chunk + * causes to be allocated but stores outside itself falls on the instance side and is not in + * these numbers. That is not an oversight, it is the only honest split, and the part that falls + * outside is measured separately by {@link #aChunkAlsoCostsBytesInsideItsInstance()}. + *

+ * + *

Why every measurement is taken twice

+ *

+ * JOL caches the reflective field list of every class it meets, and that cache hangs off the very + * {@code Class} objects the walk traverses. The first walk over a shape therefore allocates + * metadata that the second walk finds already there, which showed up as a thirty object, sixteen + * hundred byte difference between the first and the second measurement of the same chunk. Every + * figure below is consequently taken from a second pass whose first pass is discarded, after which + * repeated measurements of the same chunk are byte for byte identical. + *

+ * + *

What JOL needs to work here, and why the build says so rather than this class

+ *

+ * Two options, and both of them are JVM arguments of the test task in + * {@code falco-benchmarks/build.gradle.kts}. The measurement of an object size goes through the + * instrumentation agent JOL attaches to the running JVM, which is why the build passes + * {@code -Djdk.attach.allowAttachSelf=true} and {@code -XX:+EnableDynamicAgentLoading}. Without them + * JOL keeps answering, from a layout model instead of from the JVM, and a modelled number under + * {@code -XX:+UseCompactObjectHeaders} is a guess about a feature the model may not know. + *

+ *

+ * The second is less pleasant. On JDK 25 a plain graph walk that reaches a record class inside + * {@code java.base} dies with {@code Cannot get the field offset}, because + * {@code Unsafe#objectFieldOffset} refuses record classes. The walk gets there through any + * {@code Class} field — an {@code EventNode} holds one, so every instance of this server has that + * path — and JOL only survives it with {@code -Djol.magicFieldOffset=true}, which lets it reach + * {@code jdk.internal.misc.Unsafe} instead. + *

+ *

+ * That second option used to be set from a static initialiser of this class, and doing so is what + * made these three measurements flaky. JOL reads the option exactly once, in the class initialiser of + * its {@code HotspotUnsafe}, which runs the first time anything in the JVM touches JOL. This class + * shares its test JVM with {@link PaletteFootprintTest} and {@link EmptySectionCensusTest}, which walk + * object graphs too, and the order JUnit runs test classes in is not specified — it falls out of + * classpath scanning and changes whenever the class files are rewritten. Ran this class first, the + * property arrived in time and all three tests passed; ran one of the others first, JOL had already + * cached {@code false} and all three failed with {@code Cannot get the field offset}. Same code, same + * machine, both outcomes. A JVM argument has no such ordering, which is why the option now lives in + * the build, and {@link JolMeasurement} reads back what JOL actually decided so a lost flag fails with + * that sentence instead of with a stack trace. + *

+ *

+ * One warning appears in the log and is harmless: JOL cannot attach the Serviceability Agent under + * the default {@code ptrace_scope} of Linux and says that computed addresses are guesses. + * Nothing here uses addresses — not {@code toPrintable}, not {@code toImage}, and deliberately not + * {@code subtract} — so the warning does not touch a single number in these tables. The header of + * every table states that it did not attach, next to the mode the sizes did come from. + *

+ * + *

Why the header mode and the measurement mode are printed with every table

+ *

+ * {@code -XX:+UseCompactObjectHeaders} (JEP 519, final in 25 but off by default) changes the object + * header from twelve bytes to eight, and the research report is explicit that the gain is zero or + * eight bytes per class and never a percentage. A footprint quoted without its header mode is + * therefore not a measurement of anything, and the table header states both the mode the build + * declared through {@code -Pfalco.compactHeaders} and the header size JOL actually observed. When + * the two disagree the test fails, because a mislabelled number is worse than no number. + *

+ *

+ * The same holds for where the bytes came from. JOL has two ways of answering how large an object is + * and chooses between them at runtime, so every table also names the one that was used, read out of + * JOL rather than assumed. A run that cannot size through the instrumentation agent stops with an + * assumption instead of printing modelled numbers under a heading that claims otherwise; + * {@link JolMeasurement} is where that decision is made and explained. + *

+ * + *

Which assertions are hard, and which are not

+ *

+ * The object count of a fresh chunk can be read off the source: twenty-four sections, two + * palettes and two light carriers each, one {@code AtomicBoolean} per light carrier. Those counts + * are asserted exactly, and a change in any of them is a structural change in Minestom that this + * project wants to be told about. An absolute byte figure is not asserted that way. It moves + * with the JDK, with the header mode and with the object alignment, and a test that turns red on a JDK + * upgrade teaches nobody anything, so an absolute byte figure is only bounded generously — an empty + * chunk is asserted to be kibibytes rather than megabytes, and a chunk whose palettes have gone direct + * is asserted to be dominated by the twenty-four {@code long[1024]} arrays that arithmetic says must + * be there. + *

+ *

+ * One comparison is asserted strictly, and it is the one this class exists for: the two chunk types + * against each other. Outside the classes stage 2 declared a difference for, {@code FalcoChunk} must + * weigh exactly what {@code DynamicChunk} weighs; inside them it must weigh exactly what the table + * declares. Bytes are hard there and nowhere else, because both sides are measured in the same run of + * the same JVM, so the header mode and the alignment are the same on both and cancel — a strict + * comparison of two sides is a different thing from a constant, and every expectation of that + * comparison is derived from the Minestom side of the same walk or from an object this test builds + * next to it. A deviation would not be a tolerance to widen, it would be a finding. + *

+ * + *

The declared difference table, and why it replaced an equality

+ *

+ * Stage 1 asserted that the two chunk types retain identical objects and identical bytes in every + * class but one, of which the Falco side held exactly one — its {@code SectionBlockStorage}, the + * indirection that replaced an inherited section list. Zero was never reachable while the storage is + * a separate type, so the price was named rather than rounded away, and three injected defects were + * used to prove the comparison still bit. The most instructive of them was a primitive {@code long} + * field, which adds no object at all and fitted into the padding that was already there: only the + * byte comparison caught it. + *

+ *

+ * Stage 2 makes that equality impossible by construction, because removing objects is the point. A + * fresh {@code FalcoChunk} shares one {@code LazySectionBlockStorage#EMPTY} section instead of + * owning twenty-four, builds neither heightmap until one is asked for, and keeps one block map and a + * counter where {@code DynamicChunk} keeps two maps. Measured on the pinned build, with the sections + * of tasks 2 and 3, the lazy heightmaps of task 7 and the single block map of task 8 all in place, + * that is {@code 25} objects and {@code 840} bytes against {@code 192} and {@code 6848} — a hundred + * and sixty-seven objects fewer, not one more. + *

+ *

+ * What survives the rewrite is the property the equality had, and it is what + * {@link #assertOnlyTheDeclaredClassesDiffer} is named after: a class the Falco chunk retains and + * the plan did not declare has to fail the test. The two tables {@link #FRESH_DIFFERENCE} and + * {@link #FILLED_DIFFERENCE} name every class the two sides may differ in, the count the Falco side + * has to show for it and the bytes that count is worth; every class outside them is still asserted + * equal on both objects and bytes. A tolerance of the form "at most six kibibytes" was considered and + * rejected, because it would pass for a chunk that saved the sections and grew a field — the exact + * failure the strict comparison of stage 1 was written to catch. + *

+ *

+ * The byte half of those rows was missing when the tables were first written, and the hole it left is + * worth naming, because the shape of it recurs. A declared class was asserted on its count alone, and + * the total that was supposed to catch the rest was a sum of the very bytes it was compared against — + * true by arithmetic in every run, and therefore never the first assertion to fail. What that left + * unguarded was not a corner: {@code [I} is a declared class, and in a filled chunk it holds the index + * array of every palette that went indirect, so a Falco side with the same number of arrays and wider + * ones satisfied the whole table. Injecting exactly that — one fastutil map of the chunk constructed + * with room for eight entries instead of none — passed the class as it stood, and fails it now by + * name. Each declared row therefore carries a byte expectation that is derived from the Minestom side + * of the same walk, or from a {@link Probes} object built by this test; never from the chunk it is + * asserted against. + *

+ *

+ * Three rows of the fresh table are worth reading before the rest. The one {@code Section}, one + * {@code SkyLight}, one {@code BlockLight}, two {@code PaletteImpl} and two {@code AtomicBoolean} on + * the Falco side are not a section this chunk owns: they are the single static {@code EMPTY} + * flyweight, which no walk of the instance reaches and which a difference walk therefore charges to + * whichever chunk it starts at. The whole JVM holds one of them. That is asserted as such rather + * than assumed, by measuring two chunks at once — shared stays at one, owned would become two. + *

+ *

+ * Eight defects were injected to find out where the new comparison stops biting, and seven of them + * were caught by name: a field of an undeclared class, a second storage, a {@code long} that grows + * the chunk object, a {@code Section} materialised in the constructor, an eager + * {@code SectionBlockStorage} in place of the lazy one, a shared section that is shared per storage + * instead of per JVM — that one only by the two chunk measurement, which is why it is there — and a + * block map given room for eight entries, which changes no count anywhere and is caught only by the + * byte expectation of the two array rows. The eighth survives and is stated rather than hidden: a + * {@code boolean} field added to {@code FalcoChunk} fits into the padding the object already carries, + * so it adds no object, no byte and no shallow size, and nothing here can see it. It is caught by the + * field after it, which is the one that pushes the object over the next alignment boundary. This + * comparison measures bytes, and a field which costs no byte is a field this comparison cannot be + * asked about. + *

+ * + *

Where that padding went, and why stage 3 changed no number here

+ *

+ * Task 8 of stage 3 gave {@code FalcoChunk} a reference field, the lifecycle listener of US-3.03, and + * every figure of this class survived it untouched: same object counts, same bytes, same shallow size + * on both sides. That is a measurement rather than a coincidence, and the arithmetic behind it is + * worth writing down. On the pinned build without compact headers a chunk object is {@code 80} bytes + * on either side. Twelve of those are the header and thirty-nine are the fields of {@code Chunk} + * itself; then {@code DynamicChunk} adds six references and a {@code boolean}, which is twenty-five, + * against the five references, one {@code int} and one {@code boolean} of {@code FalcoChunk}, which + * was also twenty-five. Seventy-six rounded up to the alignment of eight leaves four bytes of padding + * on both sides, and one compressed reference is exactly four. + *

+ *

+ * The eighth injected defect above and this field are therefore the same phenomenon, and this field is + * the last one that can hide in it: {@code FalcoChunk} now fills its eighty bytes exactly, with + * nothing left over. That was verified rather than assumed. A second reference field injected next to + * the listener turns both measuring cases of this class red, on the shallow size and on the chunk + * class post — which is what the paragraph above predicts, and what makes the unchanged tables below a + * result rather than a blind spot. + *

+ * + *

Why the equivalence check runs after the measurement and not before

+ *

+ * A probe that writes to its specimen is not a probe. {@code MinestomChunks#assertSameBlocks} used to + * run first in all three places below, and on a lazy storage it was a write: it asked both chunks for + * {@code Chunk#getSections()}, which a {@code FalcoChunk} answers by giving every shared slot a + * section of its own. Every fresh Falco chunk in these tables was therefore fully materialised before + * a single byte of it was counted, and the table said so without saying so — {@code 193} objects + * against {@code 192}, the same delta the eager storage of stage 1 produced, which is exactly what a + * chunk with twenty-four sections of its own costs. The chunk that was being hidden held {@code 32} + * objects at the time of that diagnosis, which was taken with tasks 2 and 3 in place and tasks 7 and 8 + * not yet written; the {@code 25} of the section above is the same measurement after both of them + * landed, and the two numbers differ by the four objects of the heightmaps and the three of the second + * block map rather than by anything the diagnosis got wrong. See the diagnosis report of 2026-08-02 in + * {@code .superpowers/sdd/2026-08-02-falco-lazy-sections}. + *

+ *

+ * Two things follow and both are done. {@code MinestomChunks#assertSameBlocks} no longer reaches + * through {@code getSections()} at all, which is a fix every benchmark of this module shares. And the + * order here is inverted: the chunk is measured first and proved equivalent afterwards, before any + * table is printed. That keeps what the check is for — a run whose two sides disagree still fails and + * still publishes nothing — while removing the last way it can decide the number it is guarding. The + * residue is stated rather than removed: comparing the heightmaps forces both sides to compute them, + * which since task 7 means building the two a fresh Falco chunk does not have, and the column descent + * of {@code Heightmap#refresh(int, int, int)} then materialises the one section it lands in. Measured + * on the pinned build, that residue is {@code 11} objects and {@code 1 328} bytes — the two heightmaps + * with their {@code short[256]}, and the seven objects of one section — which takes the chunk from + * {@code 25} objects and {@code 840} bytes to {@code 36} and {@code 2 168}. What that residue is made + * of is asserted class by class in {@link #aFreshChunkHoldsTheObjectsTheSourceDeclares()}, which also + * prints the two totals with every run, so a third heightmap or a second materialised section turns + * this paragraph red rather than stale. It is Minestom's descent and not this class's, and after the + * inversion it lands outside every number above. + *

+ * + *

Running it

+ *

+ * The tables go to standard output, which Gradle only shows at info level, so the {@code -i} is part + * of the command rather than an extra: + *

+ * 
{@code
+ * ./gradlew :falco-benchmarks:test --tests "*ChunkFootprintTest" -i
+ * ./gradlew :falco-benchmarks:test --tests "*ChunkFootprintTest" -Pfalco.compactHeaders -i
+ * }
+ *

+ * The two runs answer the same question under the two header modes, and a number from one of them + * must never be quoted next to a number from the other. + *

+ * + * @author TheMeinerLP + * @version 2.1.1 + * @since 0.4.0 + */ +@DisplayName("The retained size of a chunk, measured with JOL") +@ResourceLock(Resources.GLOBAL) +class ChunkFootprintTest { + + /** + * The property the build sets from {@code -Pfalco.compactHeaders}. + */ + private static final String COMPACT_HEADERS = "falco.compactHeaders"; + + /** + * The object header size the JVM uses when compact object headers are enabled. + */ + private static final int COMPACT_HEADER_SIZE = 8; + + /** + * The object header size the JVM uses without compact object headers. + */ + private static final int LEGACY_HEADER_SIZE = 12; + + /** + * The distinct block state counts the footprint is measured over. + *

+ * The axis of the research report. It ends at {@code 1024} because that is where a palette has + * long left the indirect mode behind and every section stores fifteen bits per entry, which is + * the state the report claims a generated chunk is permanently stuck in. + *

+ */ + private static final int[] STATE_COUNTS = {1, 16, 64, 256, 1024}; + + /** + * How many chunks the instance side measurement builds. + *

+ * More than one, because the first chunk pays for the hash table its entry lands in and would + * report a per chunk cost roughly ten times the real one. + *

+ */ + private static final int TRACKER_CHUNKS = 16; + + /** + * The width of the label column of the breakdown table. + */ + private static final int LABEL_WIDTH = 52; + + private static final String SECTION = "net.minestom.server.instance.Section"; + private static final String PALETTE = "net.minestom.server.instance.palette.PaletteImpl"; + private static final String PALETTE_INDEX_LIST = "it.unimi.dsi.fastutil.ints.IntArrayList"; + private static final String PALETTE_REVERSE_MAP = "it.unimi.dsi.fastutil.ints.Int2IntOpenHashMap"; + private static final String SKY_LIGHT = "net.minestom.server.instance.light.SkyLight"; + private static final String BLOCK_LIGHT = "net.minestom.server.instance.light.BlockLight"; + private static final String NEEDS_SEND = "java.util.concurrent.atomic.AtomicBoolean"; + private static final String MOTION_BLOCKING = "net.minestom.server.instance.heightmap.MotionBlockingHeightmap"; + private static final String WORLD_SURFACE = "net.minestom.server.instance.heightmap.WorldSurfaceHeightmap"; + private static final String BLOCK_INDEX_MAP = "it.unimi.dsi.fastutil.ints.Int2ObjectOpenHashMap"; + private static final String SECTION_LIST = "java.util.ImmutableCollections$ListN"; + private static final String LAZY_STORAGE = "net.onelitefeather.falco.instance.LazySectionBlockStorage"; + private static final String STORAGE_VIEW = "net.onelitefeather.falco.instance.LazySectionBlockStorage$1"; + private static final String SECTION_ARRAY = "[Lnet.minestom.server.instance.Section;"; + private static final String IDENTIFIER = "java.util.UUID"; + private static final String HEIGHTS = "[S"; + private static final String PACKED_VALUES = "[J"; + private static final String INT_ARRAY = "[I"; + private static final String OBJECT_ARRAY = "[Ljava.lang.Object;"; + private static final String LIGHT_ARRAY = "[B"; + + /** + * What a fresh {@code FalcoChunk} is allowed to differ from a fresh {@code DynamicChunk} in. + *

+ * Every row was derived from the tasks of this stage before it was compared with a measurement, + * because a table that is edited until the measurement fits it asserts nothing. Six of the + * fifteen rows came back different, and where the plan and the measurement disagree it is the + * measurement that stands: the five rows of the shared section, which the plan put at zero for + * the reason the row of {@link #SECTION} corrects, and the {@code int[]} row, which the plan did + * not have at all. A class outside these fifteen still has to be equal to the Minestom side on + * both its object count and its bytes. + *

+ *

+ * Every row carries a byte expectation as well as a count, and where the two differ in shape it + * is because the class does. {@link #exactly(long, String)} multiplies the count by the size one + * instance has on the Minestom side, which is only meaningful for a class whose instances are all + * the same size and which therefore refuses a class where they are not. + * {@link #fewerBy(long, ToLongFunction, String)} and {@link #added(long, ToLongFunction, String)} + * carry the size of what was removed or added, taken from {@link Probes} — objects built by this + * test rather than read off the chunk under test, because a byte expectation read off the subject + * asserts nothing about it. + *

+ */ + private static final Map FRESH_DIFFERENCE = Map.ofEntries( + Map.entry(SECTION, exactly(1, + "the one LazySectionBlockStorage#EMPTY every slot of a fresh chunk points at. It is " + + "static and therefore exists once per JVM, but it is unreachable from the " + + "instance, so this walk charges it to whichever chunk is measured")), + Map.entry(PALETTE, exactly(2, + "the block and the biome palette of that one shared section")), + Map.entry(SKY_LIGHT, exactly(1, "the sky light carrier of that one shared section")), + Map.entry(BLOCK_LIGHT, exactly(1, "the block light carrier of that one shared section")), + Map.entry(NEEDS_SEND, exactly(2, + "one needsSend flag per light carrier of that one shared section, against forty-eight " + + "for the twenty-four sections a DynamicChunk owns")), + Map.entry(MOTION_BLOCKING, exactly(0, "task 7: no heightmap exists until one is asked for")), + Map.entry(WORLD_SURFACE, exactly(0, "task 7: no heightmap exists until one is asked for")), + Map.entry(HEIGHTS, exactly(0, "the short[256] of each heightmap that was never built")), + Map.entry(BLOCK_INDEX_MAP, exactly(1, + "task 8: one block map and an int counter instead of entries and tickableMap")), + Map.entry(INT_ARRAY, fewerBy(1, Probes::mapKeys, + "the int[] key array of the block map task 8 removed, which is the key array of an " + + "Int2ObjectOpenHashMap constructed the way DynamicChunk constructs both of " + + "its own")), + Map.entry(OBJECT_ARRAY, fewerBy(2, probes -> probes.mapValues() + probes.slotArray(), + "the Object[] value array of that same map, and the backing array of Minestom's " + + "List.of(Section...), which holds one reference per section and is therefore " + + "the size of the slot array that replaced it")), + Map.entry(SECTION_LIST, exactly(0, + "Minestom's List.of(Section...); the storage keeps the Section[] itself")), + Map.entry(SECTION_ARRAY, added(1, Probes::slotArray, + "that Section[], the slot array of the storage, one reference per section")), + Map.entry(LAZY_STORAGE, added(1, Probes::storage, + "the storage, which is what the seam of stage 1 costs")), + Map.entry(STORAGE_VIEW, added(1, Probes::storageView, + "the AbstractList that BlockStorage#views answers with"))); + + /** + * What a filled {@code FalcoChunk} is allowed to differ from a filled {@code DynamicChunk} in. + *

+ * Shorter than {@link #FRESH_DIFFERENCE} by construction: {@code MinestomChunks#fill} writes + * through {@code Chunk#setBlock}, which materialises every section and builds both heightmaps, so + * everything the flyweight and task 7 save is bought back and only the bookkeeping remains. + *

+ */ + private static final Map FILLED_DIFFERENCE = Map.ofEntries( + Map.entry(BLOCK_INDEX_MAP, exactly(1, + "task 8: one block map and an int counter instead of entries and tickableMap")), + Map.entry(INT_ARRAY, fewerBy(1, Probes::mapKeys, + "the int[] key array of the block map task 8 removed. Every other int[] of a filled " + + "chunk belongs to a palette that went indirect, and this row is what bounds " + + "them: the Falco side may hold one array fewer and not one byte more")), + Map.entry(OBJECT_ARRAY, fewerBy(2, probes -> probes.mapValues() + probes.slotArray(), + "the Object[] value array of that same map, and the backing array of Minestom's " + + "List.of(Section...), which holds one reference per section and is therefore " + + "the size of the slot array that replaced it")), + Map.entry(SECTION_LIST, exactly(0, + "Minestom's List.of(Section...); the storage keeps the Section[] itself")), + Map.entry(SECTION_ARRAY, added(1, Probes::slotArray, + "that Section[], the slot array of the storage, one reference per section")), + Map.entry(LAZY_STORAGE, added(1, Probes::storage, + "the storage, which is what the seam of stage 1 costs")), + Map.entry(STORAGE_VIEW, added(1, Probes::storageView, + "the AbstractList that BlockStorage#views answers with"))); + + /** + * The instance the Minestom side of every comparison is built in. + */ + private static InstanceContainer container; + + /** + * The instance the Falco side of every comparison is built in. + */ + private static FalcoInstance falco; + + /** + * Starts the server once and creates the two instances the chunks are built in. + */ + @BeforeAll + static void setUp() { + MinestomChunks.ensureServer(); + container = MinestomChunks.newContainer(); + falco = MinestomChunks.newFalcoInstance(); + } + + /** + * Releases the two instances so they do not outlive the class. + */ + @AfterAll + static void tearDown() { + MinestomChunks.release(container); + MinestomChunks.release(falco); + container = null; + falco = null; + } + + /** + * Measures a chunk that has never been written to and prints the full breakdown. + *

+ * This is the number the research report calls the fixed cost of a chunk, and the one every + * argument about lazy sections, shared empty sections and a leaner light representation has to + * be measured against. It is taken for both chunk types at once, because the second finding of + * this method is what the two cost against each other, which after stage 2 is a subtraction + * rather than an addition: {@code FalcoChunk} holds the classes {@link #FRESH_DIFFERENCE} + * declares, in the counts it declares, and is equal to {@code DynamicChunk} in every class that + * table does not name. + *

+ *

+ * The asserted counts on the Minestom side are the ones the source dictates rather than the ones + * that happened to be measured. Twenty-four sections come from {@code DynamicChunk.java:61-67}, + * the two palettes and the two light carriers per section from {@code Section.java:11-13}, and + * the one {@code AtomicBoolean} per light carrier from the {@code needsSend} field of + * {@code BlockLight} and {@code SkyLight}. All five are package-private types, which is why they + * are named by string here — a test that had to live inside {@code net.minestom.server.instance} + * to count them would be a heavier coupling than the count is worth. + *

+ *

+ * The one section the Falco side does show is measured a second time, from two chunks at once, + * because the count alone cannot tell a shared object from an owned one. A difference walk + * charges {@code LazySectionBlockStorage#EMPTY} to whichever chunk it starts at — the field is + * static, so no walk of the instance ever reaches it — and one section per chunk is exactly what + * a chunk that quietly materialised one would also report. Two chunks separate the two readings: + * shared stays at one, owned becomes two. + *

+ *

+ * The last measurement of this method is of the equivalence check rather than of the chunk, and it + * is the reason the check runs after everything else. {@code MinestomChunks#assertSameBlocks} asks + * both sides for their heightmaps, which on a lazy chunk builds the two that task 7 removed, and + * the column descent of {@code Heightmap#refresh(int, int, int)} then materialises the one section + * it lands in. The residue that leaves behind is asserted here class by class, so that the figure + * the class documentation quotes for it is one this run produced and not one from before task 7. + *

+ */ + @Test + @DisplayName("A fresh chunk holds the objects the source declares, and Falco holds what stage 2 declared") + void aFreshChunkHoldsTheObjectsTheSourceDeclares() { + JolMeasurement.require(); + + final Chunk minestomChunk = MinestomChunks.newChunk(container, 0, 0); + final Chunk falcoChunk = MinestomChunks.newChunk(falco, 0, 0); + final Chunk secondMinestomChunk = MinestomChunks.newChunk(container, 1, 0); + final Chunk secondFalcoChunk = MinestomChunks.newChunk(falco, 1, 0); + + final Footprint minestom = measure(minestomChunk, container); + final Footprint falcoFootprint = measure(falcoChunk, falco); + final Footprint twoMinestomChunks = measureBoth(minestomChunk, secondMinestomChunk, container); + final Footprint twoFalcoChunks = measureBoth(falcoChunk, secondFalcoChunk, falco); + final Footprint sections = measureSections(minestomChunk); + MinestomChunks.assertSameBlocks(minestomChunk, falcoChunk); + final Footprint afterTheCheck = measure(falcoChunk, falco); + + final StringBuilder out = new StringBuilder(); + appendHeader(out, "a fresh chunk, before a single block is set"); + appendProfileHeader(out); + appendProfileRow(out, "fresh", "-", "-", minestom, falcoFootprint); + out.append(System.lineSeparator()); + appendBreakdown(out, minestomChunk, minestom, sections); + appendClassTable(out, minestom); + report(out); + + assertOnlyTheDeclaredClassesDiffer(minestom, minestomChunk, falcoFootprint, falcoChunk, + FRESH_DIFFERENCE, probes(falcoChunk), "a fresh chunk"); + + assertEquals(2 * minestom.objectsOf(SECTION), twoMinestomChunks.objectsOf(SECTION), + "two DynamicChunks own two full sets of sections, which is the control this comparison " + + "needs: without it, one section per Falco chunk cannot be told apart from one " + + "section for every Falco chunk in the JVM"); + assertEquals(1, twoFalcoChunks.objectsOf(SECTION), + "two fresh FalcoChunks have to share the one EMPTY section between them, and they " + + "retained " + twoFalcoChunks.objectsOf(SECTION) + " between them"); + assertEquals(2, twoFalcoChunks.objectsOf(SECTION_ARRAY), + "what does scale with the chunk count is the slot array, one per storage"); + assertEquals(1, falcoFootprint.objectsOf(SECTION), + "a fresh Falco chunk owns no section at all. The one this walk charges it with is the " + + "shared EMPTY flyweight, which exists once per JVM and is proved shared by the " + + "two chunk measurement above; anything beyond it was materialised"); + assertEquals(2, falcoFootprint.objectsOf(NEEDS_SEND), + "forty-six of the forty-eight AtomicBoolean send flags of a fresh chunk are gone with " + + "the sections that held them; the two that remain belong to the shared EMPTY " + + "section, and the ones that come back with a materialised section are two per " + + "section and are what US-2.05 does not remove"); + assertTrue(falcoFootprint.bytes() * 4 < minestom.bytes(), + "a fresh Falco chunk retained " + falcoFootprint.bytes() + " bytes against " + + minestom.bytes() + " for a DynamicChunk; the sections are 74,9 % of that " + + "figure and both heightmaps another 16,4 %, so anything above a quarter " + + "means one of the two did not actually go"); + + assertEquals(1, afterTheCheck.objectsOf(MOTION_BLOCKING), + "the equivalence check asks for the heightmaps, so it builds the one task 7 removed"); + assertEquals(1, afterTheCheck.objectsOf(WORLD_SURFACE), + "the equivalence check asks for the heightmaps, so it builds the one task 7 removed"); + assertEquals(2, afterTheCheck.objectsOf(HEIGHTS), + "the short[256] of each of those two heightmaps"); + assertEquals(2, afterTheCheck.objectsOf(SECTION), + "the shared EMPTY section this walk charges the chunk with, plus the one the column " + + "descent of Heightmap#refresh materialised. A third would mean the descent " + + "walked further than the one section it lands in"); + report(new StringBuilder() + .append(" The equivalence check is not free on a lazy chunk: proving the two sides equal " + + "left the fresh Falco chunk at ") + .append(afterTheCheck.objects()).append(" objects and ").append(afterTheCheck.bytes()) + .append(" bytes, against ").append(falcoFootprint.objects()).append(" and ") + .append(falcoFootprint.bytes()).append(" before it. That residue is both heightmaps with " + + "their short[256] and the one section the descent materialised, and it lands " + + "outside every table above because the check runs after the measurement.") + .append(System.lineSeparator())); + + assertEquals(24, minestom.objectsOf(SECTION), "sections per overworld chunk"); + assertEquals(48, minestom.objectsOf(PALETTE), "palettes per overworld chunk, one for blocks and one for biomes per section"); + assertEquals(24, minestom.objectsOf(SKY_LIGHT), "sky light carriers per overworld chunk"); + assertEquals(24, minestom.objectsOf(BLOCK_LIGHT), "block light carriers per overworld chunk"); + assertEquals(48, minestom.objectsOf(NEEDS_SEND), "AtomicBoolean flags per overworld chunk, one per light carrier"); + assertEquals(1, minestom.objectsOf(MOTION_BLOCKING), "motion blocking heightmaps per chunk"); + assertEquals(1, minestom.objectsOf(WORLD_SURFACE), "world surface heightmaps per chunk"); + assertEquals(2, minestom.objectsOf(BLOCK_INDEX_MAP), "block index maps per chunk, entries and tickableMap"); + assertEquals(0, minestom.objectsOf(PACKED_VALUES), + "an untouched palette has bitsPerEntry == 0 and must not own a backing array yet"); + + assertTrue(minestom.objects() > 150 && minestom.objects() < 300, + "A fresh chunk retained " + minestom.objects() + " objects, which is nowhere near the " + + "roughly two hundred the section structure of Minestom dictates"); + assertTrue(minestom.bytes() > 4_096 && minestom.bytes() < 32_768, + "A fresh chunk retained " + minestom.bytes() + " bytes, which is outside the kibibyte " + + "range object headers alone can produce"); + } + + /** + * Measures the footprint over the distinct state count and the arrangement of the states. + *

+ * Two axes, because the palette is a compressor and both of its inputs decide what it costs. The + * state count decides how many bits an entry needs and whether the palette stays indirect at + * all; the arrangement decides how many distinct states a single section actually sees, which is + * why {@link FillShape#LAYERED} can be handed a thousand states and still leave every section on + * four bits. The measured distinct count is printed next to the requested one so that no row of + * this table can be read as an answer to a question it did not ask. + *

+ *

+ * The two sides are proved equal through {@code MinestomChunks#assertSameBlocks}, which walks + * every position and both heightmaps and throws. A footprint comparison of two chunks with + * different content is not a comparison. It runs after each pair has been measured and before the + * row is written, for the reason the class documentation gives: the check computes heightmaps, and + * a heightmap computation on a lazy storage allocates. Running last still stops a run whose two + * sides disagree, and it stops it before a number reaches standard output. + *

+ *

+ * The {@code fresh} row is measured on both sides rather than printed twice from the Minestom + * side. It used to be the latter, which cost nothing while the delta was zero and would now print + * a zero in the one column where the two sides differ most — a row that reports a difference it + * never measured. Its pair is now compared like every other row, which it was not: + * the two fresh chunks went unchecked here, and the only reason that never showed is that the + * check they were missing was the one destroying the row above them. + *

+ */ + @Test + @DisplayName("The state count and the arrangement decide the bytes, not the block count") + void theStateCountAndTheShapeDecideTheBytes() { + JolMeasurement.require(); + + final Chunk freshChunk = MinestomChunks.newChunk(container, 0, 0); + final Chunk freshFalcoChunk = MinestomChunks.newChunk(falco, 0, 0); + final Footprint fresh = measure(freshChunk, container); + final Footprint freshFalco = measure(freshFalcoChunk, falco); + final Probes probes = probes(freshFalcoChunk); + MinestomChunks.assertSameBlocks(freshChunk, freshFalcoChunk); + + final StringBuilder out = new StringBuilder(); + appendHeader(out, "one chunk over the distinct state count and the arrangement"); + appendProfileHeader(out); + appendProfileRow(out, "fresh", "-", "-", fresh, freshFalco); + assertOnlyTheDeclaredClassesDiffer(fresh, freshChunk, freshFalco, freshFalcoChunk, + FRESH_DIFFERENCE, probes, "fresh"); + + + long directModeBytes = 0; + long layeredAtLargestCount = 0; + + for (int states : STATE_COUNTS) { + for (FillShape shape : FillShape.values()) { + final Chunk minestomChunk = MinestomChunks.newChunk(container, 0, 0); + final Chunk falcoChunk = MinestomChunks.newChunk(falco, 0, 0); + MinestomChunks.fill(minestomChunk, states, shape); + MinestomChunks.fill(falcoChunk, states, shape); + + final Footprint minestom = measure(minestomChunk, container); + final Footprint falcoFootprint = measure(falcoChunk, falco); + MinestomChunks.assertSameBlocks(minestomChunk, falcoChunk); + appendProfileRow(out, shape.name(), Integer.toString(states), + Integer.toString(MinestomChunks.countDistinctStates(minestomChunk)), + minestom, falcoFootprint); + + assertOnlyTheDeclaredClassesDiffer(minestom, minestomChunk, falcoFootprint, falcoChunk, + FILLED_DIFFERENCE, probes, states + " states in " + shape); + assertTrue(minestom.bytes() >= fresh.bytes(), + "A filled chunk cannot retain less than an empty one, " + states + " states in " + shape); + + if (states == STATE_COUNTS[STATE_COUNTS.length - 1] && shape == FillShape.UNIFORM) { + directModeBytes = minestom.bytes(); + } + if (states == STATE_COUNTS[STATE_COUNTS.length - 1] && shape == FillShape.LAYERED) { + layeredAtLargestCount = minestom.bytes(); + } + } + } + out.append(System.lineSeparator()); + out.append(" The registry of the pinned build holds ").append(MinestomChunks.availableBlocks()) + .append(" blocks which are neither air nor a block entity. Above that count the fill") + .append(System.lineSeparator()) + .append(" falls back to further states of the same blocks, so the two halves of a curve") + .append(" over that boundary answer slightly").append(System.lineSeparator()) + .append(" different questions. LAYERED shows at most sixteen states per section and") + .append(" therefore never reaches the largest count.").append(System.lineSeparator()); + report(out); + + assertTrue(directModeBytes > 100 * 1024 && directModeBytes < 400 * 1024, + "A chunk whose sections all went direct retained " + directModeBytes + " bytes, while the " + + "twenty-four long[1024] arrays it must hold are already " + (24 * 8208) + " bytes"); + assertTrue(layeredAtLargestCount * 2 < directModeBytes, + "The arrangement has to matter: a layered chunk retained " + layeredAtLargestCount + + " bytes against " + directModeBytes + " for the same state count spread uniformly"); + } + + /** + * Measures what a chunk costs in the instance it was built for rather than in itself. + *

+ * The constructor of {@code Chunk} asks the entity tracker of its instance for a viewable + * ({@code Chunk.java:74-76}), and the tracker caches that view under a key built from the chunk + * position. Nothing ever removes it — neither unloading a chunk nor dropping the last reference + * to it — so the bytes reported here are retained by the instance for as long as the instance + * lives, and they belong to no chunk that could be measured. They are invisible in every other + * table of this class by construction, which is the reason this one exists. + *

+ *

+ * The second finding is the difference between the two instance types. An + * {@code InstanceContainer} hands the tracker a fresh {@code unmodifiableList} of its shared + * instances on every chunk construction, while a {@link FalcoInstance} is not an + * {@code InstanceContainer} and gets the {@code List.of()} singleton, so the container side + * retains one wrapper object per chunk that the Falco side does not. The report predicted that + * difference from the code; this is the measurement of it. + *

+ */ + @Test + @DisplayName("A chunk also costs bytes inside the instance it was built for") + void aChunkAlsoCostsBytesInsideItsInstance() { + JolMeasurement.require(); + + final InstanceContainer freshContainer = MinestomChunks.newContainer(); + final FalcoInstance freshFalco = MinestomChunks.newFalcoInstance(); + try { + final long[] containerCost = costInsideInstance(freshContainer); + final long[] falcoCost = costInsideInstance(freshFalco); + + final StringBuilder out = new StringBuilder(); + appendHeader(out, "what constructing " + TRACKER_CHUNKS + " chunks adds to the instance itself"); + out.append(String.format(Locale.ROOT, " %-" + LABEL_WIDTH + "s %9s %11s %11s%n", + "INSTANCE TYPE", "OBJECTS", "BYTES", "B/CHUNK")); + appendInstanceRow(out, "InstanceContainer", containerCost); + appendInstanceRow(out, "FalcoInstance", falcoCost); + out.append(System.lineSeparator()) + .append(" Nothing releases these objects again, not even unloading the chunk.") + .append(System.lineSeparator()); + report(out); + + assertTrue(containerCost[1] > 0, + "Constructing chunks has to leave something behind in the entity tracker of the instance"); + assertTrue(falcoCost[1] > 0, + "Constructing chunks has to leave something behind in the entity tracker of the instance"); + assertTrue(falcoCost[1] <= containerCost[1], + "A FalcoInstance receives the List.of() singleton instead of a fresh unmodifiable list, so " + + "it cannot cost more per chunk than an InstanceContainer, but it retained " + + falcoCost[1] + " against " + containerCost[1] + " bytes"); + } finally { + MinestomChunks.release(freshContainer); + MinestomChunks.release(freshFalco); + } + } + + /** + * States what the chunk identifier costs and why this stage does not remove it. + *

+ * US-2.08 asks for the {@code UUID} of a chunk to go, on the grounds that {@code grep + * getIdentifier} finds only its declaration in all of Minestom — which it does, at + * {@code Chunk.java:167}, with no caller anywhere in the server. It cannot go from here anyway. + * {@code Chunk.java:48} declares {@code private final UUID identifier} and {@code Chunk.java:66} + * assigns it {@code UUID.randomUUID()} in the constructor every subclass has to call. A subclass + * cannot remove a field of its superclass, and not extending {@code Chunk} is not available + * either, because {@code Instance} is typed on it throughout. What this test does instead is + * state the price, so that the story is closed by a number rather than by a shrug. + *

+ *

+ * The identifier is deliberately absent from both declared difference tables. It is one object on + * either side, so the class comparison already demands that the two chunks carry the same one, + * and a change to that is a finding rather than a saving. + *

+ */ + @Test + @DisplayName("The chunk identifier cannot be removed from a subclass, and this is what it costs") + void theChunkIdentifierIsOutOfReach() { + JolMeasurement.require(); + + final Chunk falcoChunk = MinestomChunks.newChunk(falco, 0, 0); + final Footprint falcoFootprint = measure(falcoChunk, falco); + + assertEquals(1, falcoFootprint.objectsOf(IDENTIFIER), + "every chunk of Minestom allocates one UUID in the constructor of Chunk"); + report(new StringBuilder() + .append(" The chunk identifier costs ") + .append(falcoFootprint.bytesOf(IDENTIFIER)) + .append(" bytes per chunk and is unreachable from a subclass (Chunk.java:48, :66).") + .append(System.lineSeparator())); + } + + /** + * Fails unless the two chunks differ in exactly the classes this stage declared they differ in. + *

+ * The comparison of stage 1 demanded equality everywhere except one class, and it could, because + * the seam added one object and removed none. Stage 2 removes a hundred and sixty-seven of them, + * so equality is no longer the right shape — but the property it existed for is unchanged and is + * preserved here: a class the Falco chunk retains and this table does not name still fails, on + * both its object count and its bytes. A class the table does name is asserted twice over, on the + * count the table declares and on the bytes that count is worth, and neither of those two numbers + * is read off the chunk being asserted about: the count comes from the plan, the size comes either + * from the Minestom side of the same walk or from a {@link Probes} object this test built itself. + * There is no tolerance anywhere in it, and no class is left unbounded on either axis. + *

+ *

+ * The byte side of the declared rows is the part that was missing until it was pointed out, and + * the row it was missing from most is {@link #INT_ARRAY} of {@link #FILLED_DIFFERENCE}: every + * indirect palette of a filled chunk keeps its index array in that class, so a table that declared + * only the count would have let the Falco side hold arrays of any width at all. The total at the + * end is not what closes that hole and is no longer advertised as if it were — see below. + *

+ *

+ * A tolerance was considered and rejected. "The Falco chunk retains at most six kibibytes" would + * pass for a chunk that saved the sections and grew a field, which is the exact failure the strict + * comparison of stage 1 was written to catch and the reason three defects were injected into it to + * prove that it did. + *

+ *

+ * The sum at the end is a check on the apparatus and not on the chunk, and it is worth being clear + * about which. Once every class has been compared — the declared ones against their expectation, + * the undeclared ones against the Minestom side, the chunk class as one post — the difference of + * the two totals is already determined, so this assertion cannot be the first one to fail on a + * chunk that changed. What it can still catch is a walk whose per class table does not add up to + * the total it reported, which would mean the two footprints below are not describing the same set + * of objects and that every number this class prints is suspect. + *

+ *

+ * The declared table is iterated together with the union of the two footprints rather than only + * over it. A class that vanished from both sides would otherwise never be visited, and a + * declaration of one storage would pass for a chunk that holds none — which is a hole the byte + * sum would report as an unattributable remainder instead of by name. + *

+ *

+ * One post is exempt from the per class comparison, and it is the chunk class itself. + * {@code DynamicChunk} and {@code FalcoChunk} are different classes by construction, and so are + * the lambda classes the JVM spins for the method reference each of them hands to its + * {@code CachedPacket} — those carry a generated name which need not even be stable between two + * runs of the same build. Everything whose class name starts with the name of the chunk class is + * consequently compared as a single post: same object count, same bytes. That is where a field + * added to {@code FalcoChunk} shows up first — once it costs a byte at all — and it is why + * {@code startsWith} is used rather than an equality that would let the lambda escape the + * comparison entirely. It is checked twice over, once by class name and once through + * {@code ClassLayout}, and neither of the two sees a field that fits into the padding the object + * already carries: the lifecycle listener of task 8 is such a field, and the class documentation + * says which four bytes it consumed and what proves that the next one will not fit. + *

+ * + * @param minestom the footprint of the Minestom side + * @param minestomChunk the chunk the Minestom side was measured from + * @param falcoSide the footprint of the Falco side + * @param falcoChunk the chunk the Falco side was measured from + * @param declared the expected count and byte weight per class on the Falco side, for every + * class the two sides may differ in + * @param probes the sizes the byte expectations of the declared rows are derived from + * @param context what was measured, named in every failure message + */ + private static void assertOnlyTheDeclaredClassesDiffer(Footprint minestom, Chunk minestomChunk, + Footprint falcoSide, Chunk falcoChunk, + Map declared, Probes probes, + String context) { + final String minestomType = minestomChunk.getClass().getName(); + final String falcoType = falcoChunk.getClass().getName(); + + assertEquals(minestom.bytesOf(BLOCK_INDEX_MAP) / minestom.objectsOf(BLOCK_INDEX_MAP), + probes.mapObject(), + context + ": the byte expectations of the two array rows are the size of the arrays of a " + + "map this test built, and that only states anything if it is the same map a chunk " + + "builds. The one this test built weighs " + probes.mapObject() + " bytes against " + + (minestom.bytesOf(BLOCK_INDEX_MAP) / minestom.objectsOf(BLOCK_INDEX_MAP)) + + " for the ones a DynamicChunk holds"); + + assertEquals(minestom.objectsUnder(minestomType), falcoSide.objectsUnder(falcoType), + context + ": the chunk object and the lambdas the JVM spins for it are " + + falcoSide.objectsUnder(falcoType) + " objects on the Falco side against " + + minestom.objectsUnder(minestomType) + " on the Minestom side"); + assertEquals(minestom.bytesUnder(minestomType), falcoSide.bytesUnder(falcoType), + context + ": the chunk object and the lambdas the JVM spins for it weigh " + + falcoSide.bytesUnder(falcoType) + " bytes on the Falco side against " + + minestom.bytesUnder(minestomType) + " on the Minestom side, so FalcoChunk " + + "has grown a field of its own"); + + final Set classNames = new TreeSet<>(minestom.perClass().keySet()); + classNames.addAll(falcoSide.perClass().keySet()); + classNames.addAll(declared.keySet()); + + long declaredBytes = 0; + + for (String className : classNames) { + if (className.startsWith(minestomType) || className.startsWith(falcoType)) { + continue; + } + final Declared row = declared.get(className); + + if (row == null) { + assertEquals(minestom.objectsOf(className), falcoSide.objectsOf(className), + context + ": FalcoChunk retains " + falcoSide.objectsOf(className) + " objects of " + + className + " against " + minestom.objectsOf(className) + " of DynamicChunk, " + + "and this class is not one the plan of stage 2 declared a difference for"); + assertEquals(minestom.bytesOf(className), falcoSide.bytesOf(className), + context + ": FalcoChunk retains " + falcoSide.bytesOf(className) + " bytes of " + + className + " against " + minestom.bytesOf(className) + " of DynamicChunk, " + + "and this class is not one the plan of stage 2 declared a difference for"); + continue; + } + final long expected = row.expected().applyAsLong(minestom.objectsOf(className)); + assertEquals(expected, falcoSide.objectsOf(className), + context + ": the plan declares " + expected + " objects of " + className + + " on the Falco side, against " + minestom.objectsOf(className) + + " on the Minestom side, because " + row.reason() + ". The chunk holds " + + falcoSide.objectsOf(className)); + + final long expectedBytes = row.bytes().applyAsLong(new ByteContext(expected, + minestom.objectsOf(className), minestom.bytesOf(className), probes, className)); + assertEquals(expectedBytes, falcoSide.bytesOf(className), + context + ": the plan declares " + expected + " objects of " + className + + " on the Falco side and " + expectedBytes + " bytes for them, against " + + minestom.bytesOf(className) + " bytes on the Minestom side, because " + + row.reason() + ". The chunk holds " + falcoSide.bytesOf(className) + + " bytes, so it holds the declared objects at a size nobody declared"); + declaredBytes += expectedBytes - minestom.bytesOf(className); + } + assertEquals(declaredBytes, falcoSide.bytes() - minestom.bytes(), + context + ": the two chunks differ by " + (falcoSide.bytes() - minestom.bytes()) + + " bytes while the classes the plan declared account for " + declaredBytes + + " and every other class was just asserted equal. The two do not add up, which " + + "is a statement about the walk rather than about the chunk: the per class table " + + "of a footprint has to sum to the total that footprint reports."); + assertEquals(ClassLayout.parseInstance(minestomChunk).instanceSize(), + ClassLayout.parseInstance(falcoChunk).instanceSize(), + context + ": the two chunk objects themselves must still have the same shallow size"); + } + + /** + * Measures how much an instance grows while {@link #TRACKER_CHUNKS} chunks are constructed in it. + * + * @param instance the instance to build the chunks in + * @return the object count, the byte count and the bytes per chunk, in that order + */ + private static long[] costInsideInstance(Instance instance) { + walk(instance); + final GraphLayout before = walk(instance); + + for (int index = 0; index < TRACKER_CHUNKS; index++) { + MinestomChunks.newChunk(instance, index, 0); + } + final GraphLayout after = walk(instance); + final long objects = after.totalCount() - before.totalCount(); + final long bytes = after.totalSize() - before.totalSize(); + return new long[]{objects, bytes, bytes / TRACKER_CHUNKS}; + } + + /** + * Measures everything a chunk retains that its instance does not retain anyway. + *

+ * The first pass is thrown away on purpose; see the class documentation on why a JOL walk is not + * repeatable until the metadata of every class it meets exists. + *

+ * + * @param chunk the chunk to measure, which must not be registered with the instance + * @param instance the instance the chunk was built for + * @return the footprint of the chunk alone + * @throws IllegalStateException if the chunk is reachable from the instance, which would make + * the difference between the two walks meaningless + */ + private static Footprint measure(Chunk chunk, Instance instance) { + footprintOf(instance, chunk); + final Footprint footprint = footprintOf(instance, chunk); + + if (footprint.objects() <= 0) { + throw new IllegalStateException("The chunk " + chunk.getChunkX() + ":" + chunk.getChunkZ() + + " is already reachable from its instance, so the difference between the two walks " + + "is not its footprint but zero. Measure a chunk from MinestomChunks#newChunk, " + + "which is deliberately not registered."); + } + return footprint; + } + + /** + * Measures what two chunks of the same instance retain between them. + *

+ * The number this answers that {@link #measure(Chunk, Instance)} cannot is how much of a + * footprint is shared. An object both chunks point at is walked once and counted once, so a post + * that is twice as large here as in a single measurement is owned per chunk, and one that did not + * grow at all is shared by the JVM. That distinction is the whole claim of the flyweight, and + * without a second chunk it is not observable from a footprint at all. + *

+ * + * @param first the first chunk, which must not be registered with the instance + * @param second the second chunk, which must not be registered with the instance + * @param instance the instance both chunks were built for + * @return the footprint of the two chunks together + */ + private static Footprint measureBoth(Chunk first, Chunk second, Instance instance) { + footprintOf(instance, first, second); + return footprintOf(instance, first, second); + } + + /** + * Walks the chunk together with its instance and the instance alone, and returns the difference. + * + * @param instance the instance the chunks were built for + * @param chunks the chunks to measure, walked as one graph so that anything they share is + * counted once + * @return the difference between the two walks, per class and in total + */ + private static Footprint footprintOf(Instance instance, Chunk... chunks) { + final Object[] roots = new Object[chunks.length + 1]; + roots[0] = instance; + System.arraycopy(chunks, 0, roots, 1, chunks.length); + + final GraphLayout environment = walk(instance); + final GraphLayout together = walk(roots); + return difference(together, environment); + } + + /** + * Measures everything below {@code chunk.getSections()}. + *

+ * This walk needs no instance to be subtracted, because a {@code Section} references nothing but + * its two palettes and its two light carriers and none of them reference the chunk. It is + * therefore the one part of the footprint that can be attributed without any ambiguity, which + * matters for the breakdown: inside it every {@code long[]} belongs to a palette, every + * {@code byte[]} to a light carrier and every {@code int[]} to the index structures of a + * palette, while the same three array types occur in several places once the whole chunk is + * looked at. + *

+ * + * @param chunk the chunk whose sections are measured + * @return the footprint of the section list and everything below it + */ + private static Footprint measureSections(Chunk chunk) { + walk(chunk.getSections()); + final GraphLayout layout = walk(chunk.getSections()); + return difference(layout, null); + } + + /** + * Runs a JOL graph walk and turns its two known failure modes into a readable message. + * + * @param roots the objects to start the walk from + * @return the layout of everything reachable from the roots + * @throws IllegalStateException if JOL cannot walk the graph on this JVM + */ + private static GraphLayout walk(Object... roots) { + try { + return GraphLayout.parseInstance(roots); + } catch (RuntimeException exception) { + throw new IllegalStateException("JOL could not walk the object graph on this JVM. The usual " + + "cause on JDK 25 is a record class inside java.base, which Unsafe#objectFieldOffset " + + "refuses; the build passes -Djol.magicFieldOffset=true to the test JVM for exactly " + + "that case and JolMeasurement confirmed that JOL initialised with it, so a failure " + + "here means the workaround itself stopped working and the footprint numbers cannot " + + "be produced at all.", exception); + } + } + + /** + * Subtracts one layout from another, per class and in total. + * + * @param together the layout that holds the subject and the environment + * @param environment the layout that holds the environment alone, null if there is none + * @return the difference of the two + */ + private static Footprint difference(GraphLayout together, GraphLayout environment) { + final Set> classes = new LinkedHashSet<>(together.getClasses()); + + if (environment != null) { + classes.addAll(environment.getClasses()); + } + final TreeMap perClass = new TreeMap<>(); + + for (Class type : classes) { + final long objects = together.getClassCounts().count(type) + - (environment == null ? 0 : environment.getClassCounts().count(type)); + final long bytes = together.getClassSizes().count(type) + - (environment == null ? 0 : environment.getClassSizes().count(type)); + + if (objects != 0 || bytes != 0) { + perClass.put(type.getName(), new Tally(type.getTypeName(), objects, bytes)); + } + } + final long objects = together.totalCount() - (environment == null ? 0 : environment.totalCount()); + final long bytes = together.totalSize() - (environment == null ? 0 : environment.totalSize()); + return new Footprint(objects, bytes, perClass); + } + + /** + * Writes the block every table of this class is introduced by. + * + * @param out the builder to write into + * @param subject what the table below describes + */ + private static void appendHeader(StringBuilder out, String subject) { + final int headerSize = VM.current().objectHeaderSize(); + final String declared = System.getProperty(COMPACT_HEADERS); + + assertHeaderMode(headerSize, declared); + out.append(System.lineSeparator()) + .append("=".repeat(96)).append(System.lineSeparator()) + .append(" ChunkFootprintTest: ").append(subject).append(System.lineSeparator()) + .append(" retained by the chunk alone, the instance it belongs to is subtracted") + .append(System.lineSeparator()) + .append(String.format(Locale.ROOT, " object header %d bytes, alignment %d bytes, %s%n", + headerSize, VM.current().objectAlignment(), + declared == null + ? "-P" + COMPACT_HEADERS + " not stated by the build" + : COMPACT_HEADERS + "=" + declared)) + .append(String.format(Locale.ROOT, " %s %s%n", + System.getProperty("java.vm.name"), System.getProperty("java.version"))) + .append(String.format(Locale.ROOT, " %s%n", JolMeasurement.describe())) + .append("=".repeat(96)).append(System.lineSeparator()); + } + + /** + * Fails when the header size JOL observes contradicts the mode the build declared. + * + * @param headerSize the header size JOL observed + * @param declared the value of the property the build set, null if it set none + */ + private static void assertHeaderMode(int headerSize, String declared) { + if (declared == null) { + return; + } + final int expected = Boolean.parseBoolean(declared) ? COMPACT_HEADER_SIZE : LEGACY_HEADER_SIZE; + assertEquals(expected, headerSize, + "The build declared " + COMPACT_HEADERS + "=" + declared + " but the JVM uses a header of " + + headerSize + " bytes. Every number of this run would carry the wrong label."); + } + + /** + * Writes the column titles of the profile table. + * + * @param out the builder to write into + */ + private static void appendProfileHeader(StringBuilder out) { + out.append(String.format(Locale.ROOT, " %-14s %8s %9s %9s %11s %9s %11s %9s%n", + "ARRANGEMENT", "STATES", "DISTINCT", "OBJECTS", "MINESTOM B", "OBJECTS", "FALCO B", "DELTA B")); + } + + /** + * Writes one row of the profile table. + * + * @param out the builder to write into + * @param shape the arrangement of the states, or a dash for an unfilled chunk + * @param states the requested amount of distinct states, or a dash + * @param distinct the measured amount of distinct states, or a dash + * @param minestom the footprint of the Minestom side + * @param falcoSide the footprint of the Falco side + */ + private static void appendProfileRow(StringBuilder out, String shape, String states, String distinct, + Footprint minestom, Footprint falcoSide) { + out.append(String.format(Locale.ROOT, " %-14s %8s %9s %9d %11d %9d %11d %9d%n", + shape, states, distinct, minestom.objects(), minestom.bytes(), + falcoSide.objects(), falcoSide.bytes(), falcoSide.bytes() - minestom.bytes())); + } + + /** + * Writes one row of the instance cost table. + * + * @param out the builder to write into + * @param type the name of the instance type + * @param cost the object count, the byte count and the bytes per chunk + */ + private static void appendInstanceRow(StringBuilder out, String type, long[] cost) { + out.append(String.format(Locale.ROOT, " %-" + LABEL_WIDTH + "s %9d %11d %11d%n", + type, cost[0], cost[1], cost[2])); + } + + /** + * Writes the breakdown by the posts the research report argues about. + *

+ * The section side is taken from its own walk, where every array type is unambiguous. The rest + * of the chunk is what remains after the sections, the two heightmaps and the two block index + * maps have been named, and it is reported as one row rather than split further, because the + * {@code int[]} and {@code Object[]} left in it are shared between the fastutil maps and the tag + * handler and cannot be attributed by their class alone. The full class table follows, so + * nothing is hidden behind that row. + *

+ * + * @param out the builder to write into + * @param chunk the chunk that was measured + * @param owned the footprint of the whole chunk + * @param sections the footprint of the section list and everything below it + */ + private static void appendBreakdown(StringBuilder out, Chunk chunk, Footprint owned, Footprint sections) { + final long sectionRecords = sections.bytesOf(SECTION); + final long palettes = sections.bytesOf(PALETTE, PALETTE_INDEX_LIST, PALETTE_REVERSE_MAP, + PACKED_VALUES, INT_ARRAY); + final long skyLight = sections.bytesOf(SKY_LIGHT); + final long blockLight = sections.bytesOf(BLOCK_LIGHT); + final long lightArrays = sections.bytesOf(LIGHT_ARRAY); + final long needsSend = sections.bytesOf(NEEDS_SEND); + final long sectionList = sections.bytes() - sectionRecords - palettes - skyLight - blockLight + - lightArrays - needsSend; + final long heightmaps = owned.bytesOf(MOTION_BLOCKING, WORLD_SURFACE, HEIGHTS); + final long blockIndexMaps = owned.bytesOf(BLOCK_INDEX_MAP); + final long rest = owned.bytes() - sections.bytes() - heightmaps - blockIndexMaps; + + out.append(String.format(Locale.ROOT, " %-" + LABEL_WIDTH + "s %9s %11s %8s%n", + "POST", "OBJECTS", "BYTES", "SHARE")); + appendPost(out, "the section list and everything below it", sections.objects(), sections.bytes(), owned); + appendPost(out, " Section records", sections.objectsOf(SECTION), sectionRecords, owned); + appendPost(out, " block and biome palettes, with their arrays", + sections.objectsOf(PALETTE, PALETTE_INDEX_LIST, PALETTE_REVERSE_MAP, PACKED_VALUES, INT_ARRAY), + palettes, owned); + appendPost(out, " sky light carriers", sections.objectsOf(SKY_LIGHT), skyLight, owned); + appendPost(out, " block light carriers", sections.objectsOf(BLOCK_LIGHT), blockLight, owned); + appendPost(out, " light arrays", sections.objectsOf(LIGHT_ARRAY), lightArrays, owned); + appendPost(out, " AtomicBoolean needsSend flags", sections.objectsOf(NEEDS_SEND), needsSend, owned); + appendPost(out, " the immutable list that holds the sections", + sections.objects() - sections.objectsOf(SECTION, PALETTE, PALETTE_INDEX_LIST, + PALETTE_REVERSE_MAP, PACKED_VALUES, INT_ARRAY, SKY_LIGHT, BLOCK_LIGHT, + LIGHT_ARRAY, NEEDS_SEND), + sectionList, owned); + appendPost(out, "both heightmaps, with their short[256]", + owned.objectsOf(MOTION_BLOCKING, WORLD_SURFACE, HEIGHTS), heightmaps, owned); + appendPost(out, "entries and tickableMap, the map objects", + owned.objectsOf(BLOCK_INDEX_MAP), blockIndexMaps, owned); + appendPost(out, "the " + chunk.getClass().getSimpleName() + " itself and the rest of its fields", + owned.objects() - sections.objects() + - owned.objectsOf(MOTION_BLOCKING, WORLD_SURFACE, HEIGHTS, BLOCK_INDEX_MAP), + rest, owned); + out.append(String.format(Locale.ROOT, " %-" + LABEL_WIDTH + "s %9d %11d %7.1f%%%n", + "(total)", owned.objects(), owned.bytes(), 100.0)); + out.append(System.lineSeparator()); + } + + /** + * Writes one row of the breakdown table. + * + * @param out the builder to write into + * @param label the name of the post + * @param objects the amount of objects the post holds + * @param bytes the amount of bytes the post holds + * @param owned the footprint the share is calculated against + */ + private static void appendPost(StringBuilder out, String label, long objects, long bytes, Footprint owned) { + out.append(String.format(Locale.ROOT, " %-" + LABEL_WIDTH + "s %9d %11d %7.1f%%%n", + label, objects, bytes, owned.bytes() == 0 ? 0.0 : 100.0 * bytes / owned.bytes())); + } + + /** + * Writes the full per class table, in the shape {@code GraphLayout#toFootprint} uses. + *

+ * The same information, computed as a difference of two walks rather than taken from one, which + * is what keeps the instance out of it. + *

+ * + * @param out the builder to write into + * @param owned the footprint to print + */ + private static void appendClassTable(StringBuilder out, Footprint owned) { + out.append(String.format(Locale.ROOT, " %9s %9s %11s %s%n", "COUNT", "AVG", "SUM", "DESCRIPTION")); + + owned.perClass().values().stream() + .sorted(Comparator.comparing(Tally::name)) + .forEach(tally -> out.append(String.format(Locale.ROOT, " %9d %9d %11d %s%n", + tally.objects(), tally.objects() == 0 ? 0 : tally.bytes() / tally.objects(), + tally.bytes(), tally.name()))); + out.append(String.format(Locale.ROOT, " %9d %9s %11d %s%n", + owned.objects(), "", owned.bytes(), "(total)")); + } + + /** + * Prints a finished table. + * + * @param out the builder that holds it + */ + private static void report(StringBuilder out) { + System.out.print(out); + System.out.flush(); + } + + /** + * The amount of objects and bytes one class contributes to a footprint. + * + * @param name the readable name of the class + * @param objects the amount of instances + * @param bytes the amount of bytes those instances occupy + */ + private record Tally(String name, long objects, long bytes) { + } + + /** + * One row of a declared difference table: how many objects of a class the Falco side may hold, + * and how many bytes those objects may weigh. + *

+ * The count is a function of the count on the Minestom side rather than a constant, because two + * of the rows can only be stated that way. The {@code int[]} and {@code Object[]} a chunk holds + * are the key and value arrays of its fastutil maps and the arrays of every palette that + * went indirect, so their absolute number moves with the fill — a filled chunk of this class + * shows anything between one and seventy-four of them — while what task 8 removed is exactly one + * of each, at every fill. A constant would either not hold or would pin a palette detail this + * comparison has no business pinning; {@link #fewerBy(long, ToLongFunction, String)} states the + * removal instead. + *

+ *

+ * The byte expectation exists because the count alone leaves the declared classes unbounded, and + * the row that shows why is {@link #INT_ARRAY} of {@link #FILLED_DIFFERENCE}: a filled chunk holds + * one {@code int[]} per indirect palette, all of them inside a class this table declares, so a + * Falco side that allocated the same number of arrays and made them wider would satisfy every + * count in the table. It is written as a function of the Minestom side and of {@link Probes} + * rather than as a literal, because a literal would be a figure for one header mode and this class + * runs under two. + *

+ *

+ * The reason is carried along and printed in the failure, because a bare count in a table is the + * kind of assertion the next reader deletes. + *

+ * + * @param expected how many objects the Falco side may hold, given the count on the Minestom side + * @param bytes how many bytes those objects may weigh + * @param reason why the plan of this stage declares that count + */ + private record Declared(LongUnaryOperator expected, ToLongFunction bytes, String reason) { + } + + /** + * What a byte expectation is allowed to be computed from. + * + * @param expectedObjects the count this row declares for the Falco side + * @param minestomObjects how many objects of the class the Minestom side holds + * @param minestomBytes how many bytes those objects weigh + * @param probes the sizes measured from objects this test built itself + * @param className the class the row is about, named in the failure of a rejected rule + */ + private record ByteContext(long expectedObjects, long minestomObjects, long minestomBytes, + Probes probes, String className) { + } + + /** + * Declares a count that does not depend on what the Minestom side holds. + *

+ * The byte expectation that comes with it is the count times the size one instance has on the + * Minestom side. That is only a statement for a class whose instances are all the same size, so a + * class whose bytes are not a whole multiple of its object count is rejected rather than asserted + * about: every class this factory is used for — {@code Section}, {@code PaletteImpl}, the two + * light carriers, {@code AtomicBoolean}, {@code Int2ObjectOpenHashMap}, the two heightmaps, the + * {@code short[256]} of a heightmap and {@code ListN} — has a fixed shape, and one that stopped + * having it would need a row of a different kind rather than a wider tolerance. + *

+ * + * @param objects the amount of objects the Falco side has to hold + * @param reason why the plan of this stage declares that count + * @return the declaration + */ + private static Declared exactly(long objects, String reason) { + return new Declared(minestomObjects -> objects, context -> perInstance(context) * objects, reason); + } + + /** + * Declares a count as a removal from what the Minestom side holds. + * + * @param objects the amount of objects the Falco side holds fewer of + * @param removedBytes the size of what was removed, measured from an object this test built + * @param reason why the plan of this stage declares that removal + * @return the declaration + */ + private static Declared fewerBy(long objects, ToLongFunction removedBytes, String reason) { + return new Declared(minestomObjects -> minestomObjects - objects, + context -> context.minestomBytes() - removedBytes.applyAsLong(context.probes()), reason); + } + + /** + * Declares a class the Falco side holds and the Minestom side does not. + *

+ * The Minestom side offers no size to derive a byte expectation from here, so it is taken from a + * {@link Probes} object of the same shape. For the slot array that is an independent statement: + * an array of one reference per section is a thing this test can build without asking the chunk. + * For the storage and its view list it is the weaker one — a field added to + * {@code LazySectionBlockStorage} grows the probe as well and stays invisible — so what this row + * asserts is that the chunk holds one storage of the size a plain storage has, and not that a + * plain storage is the right size. That second question belongs to the tests of the storage. + *

+ * + * @param objects the amount of objects the Falco side has to hold + * @param bytesEach the size of one of them, measured from an object this test built + * @param reason why the plan of this stage declares that addition + * @return the declaration + */ + private static Declared added(long objects, ToLongFunction bytesEach, String reason) { + return new Declared(minestomObjects -> objects, + context -> bytesEach.applyAsLong(context.probes()) * objects, reason); + } + + /** + * Returns the size one instance of a class has on the Minestom side. + * + * @param context what the byte expectation may be computed from + * @return the size of one instance, zero when the row declares no object at all + * @throws IllegalStateException if the instances of the class are not all the same size, which + * makes a per instance size a number that means nothing + */ + private static long perInstance(ByteContext context) { + if (context.expectedObjects() == 0) { + return 0; + } + if (context.minestomObjects() <= 0) { + throw new IllegalStateException("The declared row of " + context.className() + " states a count " + + "for the Falco side and takes the size of one instance from the Minestom side, which " + + "holds none. A class only the Falco side holds needs an added(...) row, whose size " + + "comes from a probe."); + } + if (context.minestomBytes() % context.minestomObjects() != 0) { + throw new IllegalStateException("The " + context.minestomObjects() + " instances of " + + context.className() + " the Minestom side holds weigh " + context.minestomBytes() + + " bytes, which is not a whole multiple of their count, so they are not all the same " + + "size and the byte expectation of an exactly(...) row cannot be stated for them."); + } + return context.minestomBytes() / context.minestomObjects(); + } + + /** + * The sizes the byte expectations of the two declared tables are derived from. + *

+ * Every one of them is measured on the running JVM from an object this test constructed, which is + * what keeps them independent of the chunk they are asserted against and correct under both header + * modes. The map is built the way {@code DynamicChunk.java:55-56} builds the two it declares, with + * an expected size of zero, so its two arrays are the arrays task 8 removed. + *

+ * + * @param mapObject the size of one {@code Int2ObjectOpenHashMap} as a chunk constructs it + * @param mapKeys the size of its {@code int[]} key array + * @param mapValues the size of its {@code Object[]} value array + * @param slotArray the size of an array of one reference per section + * @param storage the shallow size of a {@link LazySectionBlockStorage} + * @param storageView the shallow size of the list its {@code views()} answers with + */ + private record Probes(long mapObject, long mapKeys, long mapValues, long slotArray, + long storage, long storageView) { + } + + /** + * Measures the sizes the declared byte expectations are derived from. + *

+ * It runs inside a test method rather than in a static initialiser for the reason the class + * documentation gives about {@code jol.magicFieldOffset}: nothing in this class may touch JOL + * before {@link JolMeasurement#require()} has confirmed that the test JVM was started the way + * these measurements need. + *

+ * + * @param chunk the chunk the section bounds are read from, so that the slot array probe has the + * length the chunk under test gives its own + * @return the sizes, for the header mode this run uses + */ + private static Probes probes(Chunk chunk) { + final int sectionCount = chunk.getMaxSection() - chunk.getMinSection(); + final Int2ObjectOpenHashMap map = new Int2ObjectOpenHashMap<>(0); + final LazySectionBlockStorage storage = new LazySectionBlockStorage(chunk.getMinSection(), sectionCount); + + walk(map); + final Footprint mapFootprint = difference(walk(map), null); + return new Probes(mapFootprint.bytesOf(BLOCK_INDEX_MAP), + mapFootprint.bytesOf(INT_ARRAY), + mapFootprint.bytesOf(OBJECT_ARRAY), + ClassLayout.parseInstance(new Section[sectionCount]).instanceSize(), + ClassLayout.parseInstance(storage).instanceSize(), + ClassLayout.parseInstance(storage.views()).instanceSize()); + } + + /** + * Everything a subject retains, in total and per class. + * + * @param objects the amount of objects + * @param bytes the amount of bytes + * @param perClass the same numbers per class, keyed by the binary name of the class + */ + private record Footprint(long objects, long bytes, TreeMap perClass) { + + /** + * Returns how many objects of the given classes the footprint holds. + * + * @param classNames the binary names of the classes to sum over + * @return the amount of objects + */ + private long objectsOf(String... classNames) { + long total = 0; + + for (String className : classNames) { + final Tally tally = perClass.get(className); + total += tally == null ? 0 : tally.objects(); + } + return total; + } + + /** + * Returns how many bytes the objects of the given classes occupy. + * + * @param classNames the binary names of the classes to sum over + * @return the amount of bytes + */ + private long bytesOf(String... classNames) { + long total = 0; + + for (String className : classNames) { + final Tally tally = perClass.get(className); + total += tally == null ? 0 : tally.bytes(); + } + return total; + } + + /** + * Returns how many objects of a class and of everything the JVM generated from it are held. + *

+ * Prefix rather than equality, because the classes the JVM spins for a lambda or a method + * reference are named after the class that declares them and can therefore only be attributed + * that way; their own names carry a counter and an address and are not worth naming. + *

+ * + * @param prefix the binary name of the class whose objects are summed + * @return the amount of objects + */ + private long objectsUnder(String prefix) { + long total = 0; + + for (Map.Entry entry : perClass.entrySet()) { + if (entry.getKey().startsWith(prefix)) { + total += entry.getValue().objects(); + } + } + return total; + } + + /** + * Returns how many bytes a class and everything the JVM generated from it occupy. + * + * @param prefix the binary name of the class whose bytes are summed + * @return the amount of bytes + */ + private long bytesUnder(String prefix) { + long total = 0; + + for (Map.Entry entry : perClass.entrySet()) { + if (entry.getKey().startsWith(prefix)) { + total += entry.getValue().bytes(); + } + } + return total; + } + } +} diff --git a/falco-benchmarks/src/test/java/net/onelitefeather/falco/benchmark/instance/EmptySectionCensusTest.java b/falco-benchmarks/src/test/java/net/onelitefeather/falco/benchmark/instance/EmptySectionCensusTest.java new file mode 100644 index 0000000..42b2f0b --- /dev/null +++ b/falco-benchmarks/src/test/java/net/onelitefeather/falco/benchmark/instance/EmptySectionCensusTest.java @@ -0,0 +1,1201 @@ +package net.onelitefeather.falco.benchmark.instance; + +import net.kyori.adventure.nbt.BinaryTag; +import net.kyori.adventure.nbt.BinaryTagIO; +import net.kyori.adventure.nbt.BinaryTagTypes; +import net.kyori.adventure.nbt.CompoundBinaryTag; +import net.kyori.adventure.nbt.ListBinaryTag; +import net.kyori.adventure.nbt.LongArrayBinaryTag; +import net.kyori.adventure.nbt.StringBinaryTag; +import net.minestom.server.instance.Section; +import net.minestom.server.instance.palette.Palette; +import net.onelitefeather.falco.anvil.AnvilFormatException; +import net.onelitefeather.falco.anvil.ChunkDataException; +import net.onelitefeather.falco.anvil.NbtReads; +import net.onelitefeather.falco.anvil.PaletteData; +import net.onelitefeather.falco.anvil.PaletteEntryResolver; +import net.onelitefeather.falco.anvil.RegionConstants; +import net.onelitefeather.falco.anvil.RegionFile; +import net.onelitefeather.falco.anvil.SectionCodec; +import org.jetbrains.annotations.Nullable; +import org.junit.jupiter.api.Assumptions; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.parallel.ResourceLock; +import org.junit.jupiter.api.parallel.Resources; +import org.openjdk.jol.info.GraphLayout; + +import java.io.ByteArrayInputStream; +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.ArrayList; +import java.util.Comparator; +import java.util.HashMap; +import java.util.List; +import java.util.Map; +import java.util.Random; +import java.util.TreeMap; +import java.util.stream.Stream; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Counts how many sections of a real Anvil world hold nothing but air, and prices the two section + * layouts that share of empty sections decides between. + *

+ * This class is not a benchmark and measures no time. It exists because + * {@code LazySectionBenchmark} carries an axis whose interesting value, a share of ninety percent + * empty sections, was an assumption rather than a measurement. A benchmark that reports a curve over + * an assumed share reports a curve over a world nobody has. The plan for that measurement says so in + * as many words: the share has to be counted in real worlds first, with a counting tool over + * {@code falco-anvil} rather than with a benchmark. This is that tool. + *

+ * + *

What counts as empty

+ *

+ * A section is counted as empty when the {@code block_states} container it was written with holds a + * palette of exactly one entry and that entry is {@code minecraft:air}. That is the definition the + * flyweight can act on, because it is the one a loader can decide without unpacking anything: the + * format stores a section in which every block is the same with a single palette entry and without a + * {@code data} array at all. + *

+ *

+ * Three further classes are counted separately rather than folded into one number, because they + * answer different questions. A section with a single palette entry that is not air is uniform + * ground, usually stone or bedrock or deepslate, and is shareable by exactly the same mechanism with + * a second singleton rather than one, so it is the size of the next lever after the empty one. A + * section with more than one palette entry is genuinely mixed and can never be shared. A section + * without a {@code block_states} container at all is a boundary section that a server wrote for the + * light data alone; it holds no blocks, and counting it as empty would inflate the share with + * sections that a chunk of Minestom does not even allocate. + *

+ *

+ * One inaccuracy is deliberate and has to be stated rather than hidden: a section whose stored + * palette holds several entries can still be uniform in fact, if every index of its {@code data} + * array points at the same entry. The classification does not unpack the indices and therefore + * counts such a section as mixed. The count of empty sections is exact; the count of shareable + * sections is a lower bound. How far below the truth that bound sits is not left to the imagination + * either: the verification described below unpacks a bounded sample of the mixed sections and the + * report states how many of them turned out to be uniform in fact. + *

+ * + *

Why the census verifies itself

+ *

+ * A counting tool whose failure looks like a result is worse than no tool at all. Every way this one + * can go wrong produces a number, not an exception: a palette container that is looked for under the + * wrong key yields sections without blocks, a biome container mistaken for a block container yields + * a palette of strings where compounds were expected, a packed section whose {@code data} array is + * overlooked yields a palette of one entry, and each of those turns into a share that a reader has + * no way of telling apart from a share that was counted correctly. The single assertion this class + * used to carry, that it had read more than no chunk at all, would have passed through all of them. + *

+ *

+ * The census therefore carries its own evidence rather than its own opinion. It refuses to report a + * run in which a written chunk resolved no section at all, or in which a section it called air only + * still carried a {@code data} array, or in which not one non air block name was decoded anywhere in + * the sections it read. The last of those is the load bearing one: a run over thousands of written + * chunks that decodes not a single block name that is not air has misread the format, whatever the + * world looks like. + *

+ *

+ * On top of that it re-reads a bounded sample of the sections through {@code SectionCodec} and + * {@code PaletteData}, which is the same path the loader of {@code falco-anvil} takes in production, + * unpacks every one of the four thousand ninety six block entries and confirms that the class the + * fast classification assigned matches what the section actually holds. The resolver behind that + * decode interns the palette entries instead of asking a registry for them, so the verification + * needs no running server and stays a property of the file rather than of a block table. + *

+ *

+ * What it deliberately does not do is assert a share. There is no plausible range to check against, + * because plausibility depends entirely on the kind of world: a generated overworld fills its lower + * sections with stone and deepslate and leaves the upper ones empty, while a void build world is + * empty from bedrock to build limit and a share above ninety nine percent is the correct answer for + * it. An assertion that demanded terrain would fail on a world that is simply not made of terrain, + * which is inventing a number by the back door. The report instead states what kind of world it + * counted, through the generation status of the chunks it read and the block names it decoded, so a + * share can be read together with the world that produced it. + *

+ * + *

A trap in judging a world by its region files

+ *

+ * The size of a region file on disk carries almost no information about how much terrain it holds. A + * chunk occupies whole sectors of four thousand ninety six bytes, and the smallest chunk that exists + * still occupies one of them, so a region file whose thousand and twenty four chunks are all empty + * is still slightly over four megabytes. The world this class was first run against has region files + * between sixty nine kilobytes and four and a half megabytes, which reads like dense terrain and is + * not: the largest of them holds six hundred kilobytes of compressed chunk payload inside its four + * and a third megabytes, and every remaining byte is sector padding. Any judgement about a world has + * to come from its chunks, which is what this class reports, and not from {@code ls}. + *

+ * + *

Which world it reads

+ *

+ * The world is not part of this repository and never can be: it is large, often private and always + * somebody else's. {@code falco-demo/world} is the directory the demo asks a developer to drop a + * world into, and everything in it is ignored by git, so this test looks there first and accepts + * both the modern {@code dimensions///region} layout and the older {@code region} + * one. A world somewhere else is named with {@code -Dfalco.census.world=...}, which accepts a world + * root or a region directory. + *

+ *

+ * When no world is present the test does not fail. It is a tool, and a machine without a world is + * not a broken build. It stops with an assumption that names the directory it looked in and what has + * to be put there, which is the only outcome that keeps the missing number visible instead of + * turning it into a green tick. + *

+ *

+ * The read opens the region files through {@code RegionFile}, which opens its channel for reading + * and writing because that is the only mode it has. Nothing here writes, but a world on a read only + * medium cannot be counted, and a world a server is currently running on should not be. + *

+ * + *

Why the footprint is measured in the same class

+ *

+ * A share is not an argument by itself. Ninety percent of the sections being empty only matters if + * an empty section costs something, and what it costs is a JOL question rather than a JMH one. The + * second measurement of this class builds both layouts for a configurable number of chunks and asks + * JOL for the retained size of each, so the share the first measurement counted can be turned into + * bytes without anybody having to estimate an object header. The two layouts are built over the same + * section content, so the difference between them is the empty sections and nothing else. + *

+ *

+ * The chunk count is configurable and defaults below the four thousand ninety six the measurement + * plan asks for, because the graph of that many chunks is half a million objects and this class runs + * inside an ordinary test task. The report states the per chunk figure, which is the one that + * extrapolates: the only object the chunks share is the empty section itself, so the total for any + * chunk count is the per chunk figure times that count plus a constant of a few hundred bytes. + *

+ *

+ * That second measurement asks {@link JolMeasurement#require()} first, and the census above it + * deliberately does not. JOL answers a size question in one of two ways — through the instrumentation + * agent it attached to the JVM, or from a layout model when the attach failed — and it does not say + * which, so a byte figure has to name its mode or not be printed. The census counts sections in a + * file and never asks JOL anything, so a JVM without an agent is no reason to leave it uncounted. The + * footprint report prints the mode next to the object header mode for the same reason it prints that + * one at all. + *

+ * + *

Running it

+ * 
{@code
+ * ./gradlew :falco-benchmarks:test --tests "*EmptySectionCensusTest" -i
+ * ./gradlew :falco-benchmarks:test --tests "*EmptySectionCensusTest" -i \
+ *     -Dfalco.census.world=/srv/worlds/survival -Dfalco.census.chunks=16384
+ * ./gradlew :falco-benchmarks:test --tests "*EmptySectionCensusTest" -i \
+ *     -Dfalco.census.jolChunks=4096
+ * }
+ *

+ * The build already passes {@code -Djdk.attach.allowAttachSelf=true} to the test JVM and switches + * {@code -XX:+UseCompactObjectHeaders} through {@code -Pfalco.compactHeaders}, so the footprint can + * be taken under both header layouts without touching a build file. The report prints which of the + * two it ran under, because a footprint without that flag is not comparable to one with it. + *

+ * + * @author TheMeinerLP + * @version 1.1.0 + * @since 0.4.0 + */ +@ResourceLock(Resources.GLOBAL) +class EmptySectionCensusTest { + + /** + * The system property that names the world to count in. + */ + private static final String WORLD_PROPERTY = "falco.census.world"; + + /** + * The system property that caps how many chunks are read. + */ + private static final String CHUNK_PROPERTY = "falco.census.chunks"; + + /** + * The system property that decides how many chunks the footprint is taken over. + */ + private static final String JOL_CHUNK_PROPERTY = "falco.census.jolChunks"; + + /** + * The system property that restricts the count to chunks of one generation status. + *

+ * A region file holds chunks at every stage the generator has reached, and the early stages carry + * no terrain at all. Counting them together with the finished ones does not measure a world, it + * measures how far its generator happened to get: a chunk at {@code minecraft:structure_starts} + * contributes twenty-four empty sections and is indistinguishable, in the total, from a section + * that is empty because the world has nothing there. Setting this to {@code minecraft:full} + * yields the share a server actually holds in memory once the chunk is playable, which is the + * only share a decision about sharing empty sections can rest on. + *

+ */ + private static final String STATUS_PROPERTY = "falco.census.status"; + + /** + * The system property the build sets to say whether compact object headers are on. + */ + private static final String COMPACT_HEADERS_PROPERTY = "falco.compactHeaders"; + + /** + * The directory the demo asks a developer to drop a world into. + */ + private static final Path DEMO_WORLD = Path.of("falco-demo", "world"); + + /** + * The amount of directory levels the search walks upwards looking for the demo world. + */ + private static final int SEARCH_DEPTH = 6; + + /** + * The amount of chunks the census reads unless it is told otherwise. + */ + private static final int DEFAULT_CHUNK_LIMIT = 4096; + + /** + * The amount of chunks the footprint is taken over unless it is told otherwise. + */ + private static final int DEFAULT_JOL_CHUNKS = 256; + + /** + * The amount of chunks the measurement plan asks the footprint to be reported for. + */ + private static final int REPORTED_CHUNKS = 4096; + + /** + * The amount of sections a chunk of a full height overworld holds. + */ + private static final int SECTION_COUNT = 24; + + /** + * The amount of distinct block states a section that is not empty is filled from. + */ + private static final int FILLED_STATES = 64; + + /** + * The shares of empty sections the footprint is reported for, in percent. + */ + private static final int[] REPORTED_SHARES = {0, 50, 62, 90}; + + /** + * The name of air in the block palette of the format. + */ + private static final String AIR_NAME = "minecraft:air"; + + /** + * The key of the section list inside a chunk. + */ + private static final String SECTIONS_KEY = "sections"; + + /** + * The key of the block palette container inside a section. + */ + private static final String BLOCK_STATES_KEY = "block_states"; + + /** + * The key of the palette inside a palette container. + */ + private static final String PALETTE_KEY = "palette"; + + /** + * The key of the name of a palette entry. + */ + private static final String NAME_KEY = "Name"; + + /** + * The key of the packed palette indices inside a palette container. + */ + private static final String DATA_KEY = "data"; + + /** + * The key of the generation status inside a chunk. + */ + private static final String STATUS_KEY = "Status"; + + /** + * The key of the section height inside a section. + */ + private static final String SECTION_Y_KEY = "Y"; + + /** + * The amount of block entries a section holds. + */ + private static final int BLOCK_ENTRIES = 16 * 16 * 16; + + /** + * The amount of sections of each storage shape the verification decodes in full. + *

+ * The cap is per shape rather than overall because the two shapes are wildly unequal in number + * and the interesting one is the rarer. A world of empty sections would spend an entire budget on + * data less sections and never unpack a packed one, which is exactly the section a misread of the + * format hides in. + *

+ */ + private static final int VERIFIED_PER_SHAPE = 2048; + + /** + * The amount of block names the report lists to describe what the world is built of. + */ + private static final int REPORTED_NAMES = 12; + + /** + * The suffix of an Anvil region file. + */ + private static final String REGION_SUFFIX = ".mca"; + + /** + * The offset that turns a section height into an index of the per height tables. + */ + private static final int Y_OFFSET = 64; + + /** + * The length of the per height tables, which covers every section height a dimension can use. + */ + private static final int Y_RANGE = 192; + + /** + * The reader the chunks are parsed with. The payload is already decompressed at that point. + */ + private static final BinaryTagIO.Reader TAG_READER = BinaryTagIO.unlimitedReader(); + + /** + * Counts the empty sections of a real world and reports the share. + *

+ * The test asserts nothing about the share itself. There is no correct value to assert against: + * the share is the property of the world that was counted, and a test that demanded a particular + * one would be inventing the very number this tool exists to stop people from inventing. A range + * would be no better, because a generated overworld and a void build world sit at opposite ends + * of the scale and both are legitimate worlds to count. + *

+ *

+ * What it does assert is that the census read the format it thinks it read. The classes have to + * add up to the sections, the per height tables have to add up to the classes, every written + * chunk has to have resolved sections, no section counted as air only may carry packed data, the + * run has to have decoded at least one block name that is not air, and the sample the decoder of + * {@code falco-anvil} re-read has to agree with how the census sorted it. Each of those catches a + * different way of turning a misread file into a share that looks like a measurement, and none of + * them assumes what the world is made of. + *

+ * + *

+ * A chunk this run cannot read fails the test rather than being skipped. The reasoning is spelled + * out at {@link #count(Path, int, String)}: the number this test produces is a distribution, and a + * distribution counted over the subset of chunks that happened to parse is not the distribution of + * the world. + *

+ * + * @throws IOException if a region file cannot be read + * @throws AnvilFormatException if a region file or one of its chunks does not hold what the + * format requires, which invalidates the count rather than one chunk + */ + @Test + void testTheEmptySectionShareOfARealWorld() throws IOException, AnvilFormatException { + final Path regionDirectory = locateRegionDirectory(); + + Assumptions.assumeTrue(regionDirectory != null, () -> "No Anvil world was found. The census needs a " + + "world with region files, either below " + DEMO_WORLD + " next to this repository or named " + + "with -D" + WORLD_PROPERTY + "=. The world root is the " + + "directory that holds level.dat and either region/ or dimensions///region. " + + "Until this has run over a real world, the share of empty sections that " + + "LazySectionBenchmark sweeps over is an assumption and not a measurement"); + + final int chunkLimit = intProperty(CHUNK_PROPERTY, DEFAULT_CHUNK_LIMIT); + final String statusFilter = System.getProperty(STATUS_PROPERTY); + final Census census = count(regionDirectory, chunkLimit, statusFilter); + + System.out.println(report(regionDirectory, chunkLimit, statusFilter, census)); + + assertTrue(census.chunks() > 0, "The region directory " + regionDirectory + + (statusFilter == null + ? " holds region files but none of them marks a chunk as written" + : " holds no chunk at status " + statusFilter + ", so nothing was counted")); + assertTrue(census.sections() > 0, "The " + census.chunks() + + " chunks that were read hold no section at all, which no written chunk does"); + assertEquals(census.sections(), + census.empty() + census.uniform() + census.mixed() + census.withoutBlockStates(), + "The counted classes do not add up to the counted sections"); + assertEquals(census.empty(), sum(census.emptyByY()), + "The empty sections per section height do not add up to the counted empty sections"); + assertEquals(census.sections(), sum(census.totalByY()), + "The sections per section height do not add up to the counted sections, so the census " + + "met a section height outside the range a dimension can use"); + + assertEquals(0, census.chunksWithoutSections(), "Of the " + census.chunks() + " chunks that were " + + "read, " + census.chunksWithoutSections() + " resolved no section at all. A written " + + "chunk always stores sections, so the section list was looked for under a key this " + + "world does not use and every share below is a share of nothing"); + assertEquals(0, census.packedEmpty(), "Of the " + census.empty() + " sections counted as air " + + "only, " + census.packedEmpty() + " still store a packed data array. The format writes " + + "a section of a single repeated block without one, so those sections hold more than the " + + "one palette entry the census looked at and the share of empty sections is too high"); + assertTrue(census.nonAirNames().size() > 0, "The " + census.chunks() + " chunks that were read " + + "decoded not a single block name other than air. A world can be empty, but a written " + + "chunk that holds literally nothing anywhere is a misread of the format rather than a " + + "measurement, so the share of empty sections cannot be trusted"); + assertEquals(0, census.verification().mismatches(), "The decoder of the loader disagrees with the " + + "census about " + census.verification().mismatches() + " of the sections it re-read: " + + census.verification().firstMismatch()); + } + + /** + * Adds up a per height table. + * + * @param values the table to add up + * @return the sum of the table + */ + private static int sum(int[] values) { + int total = 0; + + for (int value : values) { + total += value; + } + return total; + } + + /** + * Measures what the two section layouts retain, for every share of empty sections the benchmark + * sweeps over. + *

+ * Both layouts are built from the same content: the sections that are not empty hold a filled + * block palette in both, and the only difference is what sits in the slots that are empty. In the + * eager layout that is a {@code Section} of its own, exactly as the constructor of + * {@code DynamicChunk} leaves it; in the lazy layout it is one shared section that every chunk of + * the run points at. The difference between the two totals is therefore the price of the eager + * empty sections and nothing else. + *

+ *

+ * The block states the filled sections hold are synthetic. This test does not start a server and + * has no registry to draw real ones from, and it does not need one: what a filled section retains + * is decided by the length of its {@code long[]}, which follows from the number of distinct values + * and not from what those values mean. + *

+ */ + @Test + void testTheFootprintOfBothSectionLayouts() { + JolMeasurement.require(); + + final int chunks = intProperty(JOL_CHUNK_PROPERTY, DEFAULT_JOL_CHUNKS); + final StringBuilder report = new StringBuilder(); + + report.append("Section layout footprint over ").append(chunks).append(" chunks of ") + .append(SECTION_COUNT).append(" sections, compact object headers ") + .append(System.getProperty(COMPACT_HEADERS_PROPERTY, "unknown")).append('\n') + .append(JolMeasurement.describe()).append('\n') + .append(String.format("%-8s %16s %16s %16s %16s%n", + "empty", "eager bytes", "lazy bytes", "saved/chunk", "saved/" + REPORTED_CHUNKS)); + + for (int share : REPORTED_SHARES) { + final int filled = SECTION_COUNT - SECTION_COUNT * share / 100; + final Section[][] eager = buildLayouts(chunks, filled, false); + final Section[][] lazy = buildLayouts(chunks, filled, true); + + final long eagerBytes = GraphLayout.parseInstance((Object) eager).totalSize(); + final long lazyBytes = GraphLayout.parseInstance((Object) lazy).totalSize(); + final long savedPerChunk = (eagerBytes - lazyBytes) / chunks; + + report.append(String.format("%7d%% %16d %16d %16d %16d%n", + share, eagerBytes, lazyBytes, savedPerChunk, savedPerChunk * REPORTED_CHUNKS)); + + assertTrue(lazyBytes <= eagerBytes, "The lazy layout retains " + lazyBytes + + " bytes at a share of " + share + " percent empty sections while the eager one " + + "retains " + eagerBytes + ", so sharing the empty sections made the chunk larger"); + + if (share > 0) { + assertTrue(lazyBytes < eagerBytes, "The lazy layout retains exactly as much as the eager " + + "one at a share of " + share + " percent empty sections, which means the shared " + + "section was not installed and the measurement compared a layout with itself"); + } + } + System.out.println(report); + } + + /** + * Builds one section layout per chunk. + * + * @param chunks the amount of chunks to build + * @param filled the amount of sections per chunk that hold blocks + * @param shared whether the empty sections are one shared object or one object per slot + * @return the built layouts + */ + private static Section[][] buildLayouts(int chunks, int filled, boolean shared) { + final Section empty = new Section(); + final Section template = filledSection(); + final Section[][] layouts = new Section[chunks][]; + + for (int chunk = 0; chunk < chunks; chunk++) { + final Section[] sections = new Section[SECTION_COUNT]; + + for (int index = 0; index < SECTION_COUNT; index++) { + if (index < filled) { + sections[index] = template.clone(); + } else { + sections[index] = shared ? empty : new Section(); + } + } + layouts[chunk] = sections; + } + return layouts; + } + + /** + * Builds a section whose block palette holds the configured amount of distinct states. + * + * @return the built section + */ + private static Section filledSection() { + final Section section = new Section(); + final Palette palette = section.blockPalette(); + final Random random = new Random(20260731L); + + palette.setAll((x, y, z) -> 1 + random.nextInt(FILLED_STATES)); + return section; + } + + /** + * Counts the sections of every chunk the region directory holds, up to the given limit. + * + *

Why an unreadable chunk stops the count instead of being skipped

+ *

+ * The format faults of {@code falco-anvil} are checked, so this method has to say what it does + * with one, and it lets every one of them through. Catching a {@link ChunkDataException} around + * the section loop and carrying on with the next chunk would compile, would keep the run green on + * any world, and would be the one wrong answer: this method does not produce a value that a + * missing chunk merely makes less precise, it produces a distribution. Skipping the + * chunks that fail to parse counts the distribution of the chunks that happened to parse, and + * those two are the same number only if the unreadable chunks are distributed like the readable + * ones — which is exactly what nobody can know about a file that could not be read. + *

+ *

+ * The direction of the error is not even unknown. A chunk that fails on its palette or its packed + * data is a chunk with content; a section of air alone is a single palette entry and no data array + * at all and has almost nothing left to fail on. Dropping the failures therefore drops non empty + * sections by preference and pushes the share of empty ones up — in favour of the very layout this + * census exists to price. A silent skip would bias the measurement towards the answer its author + * would like to hear, which is the failure mode the class documentation above already spends four + * paragraphs guarding against. + *

+ *

+ * A failure here is also worth more as a failure than as a smaller sample. This is a tool run by + * hand against somebody's real world, and a format fault it hits is either a bug in the loader + * this project ships or a genuinely broken world; both are findings, and both are lost the moment + * a counter swallows them. The missing world is the one case that is not a defect, and that one is + * already handled where it belongs, by an assumption in the test rather than by a catch here. + *

+ * + * @param regionDirectory the directory the region files sit in + * @param chunkLimit the amount of chunks to stop after + * @param statusFilter the generation status a chunk has to carry to be counted, or {@code null} + * to count every chunk the region files hold + * @return the counted census + * @throws IOException if a region file cannot be read or a chunk cannot be decompressed + * @throws AnvilFormatException if a region file or one of its chunks contradicts the format, in + * which case the count is abandoned rather than continued without it + */ + private static Census count(Path regionDirectory, int chunkLimit, @Nullable String statusFilter) + throws IOException, AnvilFormatException { + final List files = regionFiles(regionDirectory); + final int[] totalByY = new int[Y_RANGE]; + final int[] emptyByY = new int[Y_RANGE]; + final Map nonAirNames = new TreeMap<>(); + final Map statuses = new TreeMap<>(); + final Verification verification = new Verification(); + int readFiles = 0; + int chunks = 0; + int chunksWithoutSections = 0; + int sections = 0; + int empty = 0; + int uniform = 0; + int mixed = 0; + int withoutBlockStates = 0; + int packedEmpty = 0; + + for (Path file : files) { + if (chunks >= chunkLimit) { + break; + } + readFiles++; + + try (RegionFile region = RegionFile.open(file)) { + // The region file masks the coordinates into the region itself, so the local ones + // address the same entries the absolute ones would. + for (int localZ = 0; localZ < RegionConstants.REGION_SIZE && chunks < chunkLimit; localZ++) { + for (int localX = 0; localX < RegionConstants.REGION_SIZE && chunks < chunkLimit; localX++) { + final RegionFile.RawChunk raw = region.readRaw(localX, localZ); + + if (raw == null) { + continue; + } + final CompoundBinaryTag data = TAG_READER.read( + new ByteArrayInputStream(raw.decompress()), BinaryTagIO.Compression.NONE); + final ListBinaryTag list = NbtReads.optionalList(data, SECTIONS_KEY, BinaryTagTypes.COMPOUND); + + final String status = NbtReads.optionalString(data, STATUS_KEY); + statuses.merge(status == null ? "" : status, 1, Integer::sum); + + if (statusFilter != null && !statusFilter.equals(status)) { + continue; + } + chunks++; + + if (list.size() == 0) { + chunksWithoutSections++; + } + + for (int index = 0; index < list.size(); index++) { + final CompoundBinaryTag section = list.getCompound(index); + final int sectionY = NbtReads.integer(section, SECTION_Y_KEY); + final int slot = sectionY + Y_OFFSET; + final CompoundBinaryTag blockStates = NbtReads.optionalCompound(section, BLOCK_STATES_KEY); + final SectionClass sectionClass = classify(blockStates); + sections++; + + if (slot >= 0 && slot < Y_RANGE) { + totalByY[slot]++; + } + switch (sectionClass) { + case EMPTY -> { + empty++; + if (slot >= 0 && slot < Y_RANGE) { + emptyByY[slot]++; + } + // A palette of a single air entry describes a section in which + // every block is air, which the format writes without any packed + // data at all. Packed data next to such a palette means the + // classification looked at something other than what the section + // stores, and the share it produced is not a measurement. + if (blockStates != null && blockStates.get(DATA_KEY) instanceof LongArrayBinaryTag) { + packedEmpty++; + } + } + case UNIFORM -> uniform++; + case MIXED -> mixed++; + case NO_BLOCK_STATES -> withoutBlockStates++; + } + if (blockStates != null) { + collectNames(blockStates, nonAirNames); + verification.verify(blockStates, sectionClass); + } + } + } + } + } + } + return new Census(readFiles, files.size(), chunks, chunksWithoutSections, sections, empty, uniform, + mixed, withoutBlockStates, packedEmpty, totalByY, emptyByY, nonAirNames, statuses, verification); + } + + /** + * Decides which class a stored section belongs to. + * + * @param blockStates the block palette container of the section, or null if it holds none + * @return the class of the section + * @throws ChunkDataException if the container holds a palette entry without a name, which leaves + * the section unclassifiable rather than empty + */ + private static SectionClass classify(@Nullable CompoundBinaryTag blockStates) throws ChunkDataException { + if (blockStates == null) { + return SectionClass.NO_BLOCK_STATES; + } + final ListBinaryTag palette = NbtReads.optionalList(blockStates, PALETTE_KEY, BinaryTagTypes.COMPOUND); + + if (palette.size() == 0) { + return SectionClass.NO_BLOCK_STATES; + } + if (palette.size() > 1) { + return SectionClass.MIXED; + } + return AIR_NAME.equals(NbtReads.string(palette.getCompound(0), NAME_KEY)) + ? SectionClass.EMPTY + : SectionClass.UNIFORM; + } + + /** + * Records every block name of a palette container that is not air. + *

+ * The names are the evidence that the census decoded block content rather than an arbitrary + * structure that happens to parse. They also describe the world well enough for a reader to tell + * a generated overworld from a void build world, which is the difference a share of empty + * sections has to be read against. + *

+ * + * @param blockStates the block palette container of a section + * @param names the table the names are counted into + * @throws ChunkDataException if the container holds a palette entry without a name, which would + * leave the evidence of a correct read incomplete + */ + private static void collectNames(CompoundBinaryTag blockStates, Map names) + throws ChunkDataException { + final ListBinaryTag palette = NbtReads.optionalList(blockStates, PALETTE_KEY, BinaryTagTypes.COMPOUND); + + for (int index = 0; index < palette.size(); index++) { + final String name = NbtReads.string(palette.getCompound(index), NAME_KEY); + + if (!AIR_NAME.equals(name)) { + names.merge(name, 1, Integer::sum); + } + } + } + + /** + * Renders the census as the report the tool exists to produce. + * + * @param regionDirectory the directory that was counted + * @param chunkLimit the amount of chunks the run was allowed to read + * @param statusFilter the generation status the run was restricted to, or {@code null} + * @param census the counted census + * @return the report + */ + private static String report(Path regionDirectory, int chunkLimit, @Nullable String statusFilter, + Census census) { + final StringBuilder report = new StringBuilder(); + report.append("Empty section census of ").append(regionDirectory).append('\n') + .append("counted chunks ").append(statusFilter == null + ? "every status, including the ones the generator has not finished" + : "only status " + statusFilter).append('\n') + .append("region files read ").append(census.readFiles()).append(" of ") + .append(census.regionFiles()).append('\n') + .append("chunks read ").append(census.chunks()).append(" (limit ") + .append(chunkLimit).append(")\n") + .append("sections stored ").append(census.sections()).append('\n') + .append(line("empty (air only)", census.empty(), census.sections())) + .append(line("uniform non air", census.uniform(), census.sections())) + .append(line("mixed", census.mixed(), census.sections())) + .append(line("without blocks", census.withoutBlockStates(), census.sections())) + .append(line("shareable total", census.empty() + census.uniform(), census.sections())) + .append('\n') + .append("what the world is made of\n") + .append("chunk status ").append(census.statuses()).append('\n') + .append("block names ").append(census.nonAirNames().size()) + .append(" other than air\n") + .append("most common ").append(topNames(census.nonAirNames())).append('\n') + .append('\n') + .append("verification against the decoder of the loader\n") + .append("sections unpacked ").append(census.verification().packedVerified) + .append(" packed, ").append(census.verification().flatVerified).append(" without data\n") + .append("mismatches ").append(census.verification().mismatches()).append('\n') + .append("mixed but uniform ").append(census.verification().mixedButUniform) + .append(" of the verified mixed sections, ").append(census.verification().mixedButAir) + .append(" of them air\n") + .append('\n') + .append("empty share by section height\n") + .append(String.format("%6s %10s %10s %8s%n", "Y", "sections", "empty", "share")); + + for (int slot = 0; slot < Y_RANGE; slot++) { + if (census.totalByY()[slot] == 0) { + continue; + } + report.append(String.format("%6d %10d %10d %7.1f%%%n", slot - Y_OFFSET, census.totalByY()[slot], + census.emptyByY()[slot], 100.0 * census.emptyByY()[slot] / census.totalByY()[slot])); + } + return report.toString(); + } + + /** + * Renders the most common block names of the world. + * + * @param names every block name other than air, with the amount of palettes holding it + * @return the rendered names, or a note that the world holds none + */ + private static String topNames(Map names) { + if (names.isEmpty()) { + return "none, the sections that were read hold nothing but air"; + } + return names.entrySet().stream() + .sorted(Map.Entry.comparingByValue().reversed()) + .limit(REPORTED_NAMES) + .map(entry -> entry.getKey() + " " + entry.getValue()) + .reduce((left, right) -> left + ", " + right) + .orElseThrow(); + } + + /** + * Renders one line of the class table. + * + * @param label the name of the class + * @param value the amount of sections in the class + * @param total the amount of sections that were counted + * @return the rendered line + */ + private static String line(String label, int value, int total) { + return String.format("%-18s %10d %6.2f%%%n", label, value, total == 0 ? 0.0 : 100.0 * value / total); + } + + /** + * Finds the region directory of the world the census reads. + * + * @return the region directory or null if no world was found + */ + private static @Nullable Path locateRegionDirectory() { + final String configured = System.getProperty(WORLD_PROPERTY); + + if (configured != null && !configured.isBlank()) { + return regionDirectoryOf(Path.of(configured)); + } + Path candidate = Path.of("").toAbsolutePath(); + + for (int depth = 0; depth < SEARCH_DEPTH && candidate != null; depth++, candidate = candidate.getParent()) { + final Path world = candidate.resolve(DEMO_WORLD); + + if (!Files.isDirectory(world)) { + continue; + } + final Path region = regionDirectoryOf(world); + + if (region != null) { + return region; + } + } + return null; + } + + /** + * Resolves the region directory of a world root. + *

+ * Both layouts are accepted. A world written by a recent server keeps its region files under + * {@code dimensions///region} and an older one under {@code region}, and the + * directory the demo asks for a world in may hold the world root one level further down. + *

+ * + * @param root the world root, a region directory or a directory holding a world root + * @return the region directory or null if none of the layouts holds region files + */ + private static @Nullable Path regionDirectoryOf(Path root) { + final Path direct = directRegionDirectory(root); + + if (direct != null) { + return direct; + } + if (!Files.isDirectory(root)) { + return null; + } + try (Stream entries = Files.list(root)) { + final List directories = entries.filter(Files::isDirectory).sorted().toList(); + + for (Path entry : directories) { + final Path nested = directRegionDirectory(entry); + + if (nested != null) { + return nested; + } + } + } catch (IOException exception) { + return null; + } + return null; + } + + /** + * Resolves the region directory of a world root without descending into unrelated directories. + * + * @param root the world root or a region directory + * @return the region directory or null if neither layout holds region files + */ + private static @Nullable Path directRegionDirectory(Path root) { + if (holdsRegionFile(root)) { + return root; + } + final Path legacy = root.resolve("region"); + + if (holdsRegionFile(legacy)) { + return legacy; + } + final Path current = root.resolve("dimensions").resolve("minecraft").resolve("overworld").resolve("region"); + return holdsRegionFile(current) ? current : null; + } + + /** + * Decides whether a directory holds at least one region file. + * + * @param directory the directory to check + * @return whether the directory holds a region file + */ + private static boolean holdsRegionFile(Path directory) { + return !regionFiles(directory).isEmpty(); + } + + /** + * Lists the region files of a directory in a stable order. + * + * @param directory the directory to list + * @return the region files, or an empty list if the directory holds none or cannot be read + */ + private static List regionFiles(Path directory) { + if (!Files.isDirectory(directory)) { + return List.of(); + } + try (Stream entries = Files.list(directory)) { + final List files = new ArrayList<>(entries + .filter(Files::isRegularFile) + .filter(path -> path.getFileName().toString().endsWith(REGION_SUFFIX)) + .toList()); + files.sort(Comparator.comparing(Path::toString)); + return files; + } catch (IOException exception) { + return List.of(); + } + } + + /** + * Reads an int from a system property. + * + * @param key the name of the property + * @param defaultValue the value to use if the property is absent or unreadable + * @return the value of the property + */ + private static int intProperty(String key, int defaultValue) { + final String value = System.getProperty(key); + + if (value == null || value.isBlank()) { + return defaultValue; + } + try { + final int parsed = Integer.parseInt(value.trim()); + return parsed > 0 ? parsed : defaultValue; + } catch (NumberFormatException exception) { + return defaultValue; + } + } + + /** + * Re-reads a bounded sample of the sections through the decoder the loader uses and confirms + * that the fast classification agrees with what the section actually holds. + *

+ * The classification looks at the shape of a palette container and never unpacks it, which is + * what makes a census over thousands of chunks cheap and is also what makes every one of its + * failure modes silent. This class closes that gap for a sample: it hands the very same container + * to {@code SectionCodec}, unpacks all four thousand ninety six block entries through + * {@code PaletteData} and compares the result against the class the container was sorted into. A + * section the census called air only whose entries are not all air, or one it called uniform + * whose entries are not all the same, is a defect of the census and not a property of the world. + *

+ *

+ * The budget is spent per storage shape rather than in one pool. Packed sections are the rare + * ones in almost every world and the ones a misread of the format hides in, so they get a budget + * of their own that a flood of data less sections cannot exhaust. + *

+ *

+ * The decode resolves palette entries through an interning resolver instead of a block registry. + * The verification asks whether the entries of a section are all equal and whether they are all + * air, and both questions are answered by identity of the entries rather than by their meaning, + * so no server has to be started to answer them. The properties of an entry take part in that + * identity, because a section of oak stairs facing four ways is not a uniform section. + *

+ */ + private static final class Verification { + + private final InterningResolver resolver = new InterningResolver(); + private final int airId = this.resolver.toId(AIR_NAME, null); + + private int packedBudget = VERIFIED_PER_SHAPE; + private int flatBudget = VERIFIED_PER_SHAPE; + private int packedVerified; + private int flatVerified; + private int mismatches; + private @Nullable String firstMismatch; + private int mixedButUniform; + private int mixedButAir; + + /** + * Verifies one section against its class if the budget of its storage shape allows it. + * + * @param blockStates the block palette container of the section + * @param sectionClass the class the census sorted the section into + * @throws ChunkDataException if the container cannot be decoded, which is the strongest signal + * this class can give: the census sorted a section the loader of + * this project cannot read at all + */ + private void verify(CompoundBinaryTag blockStates, SectionClass sectionClass) throws ChunkDataException { + if (sectionClass == SectionClass.NO_BLOCK_STATES) { + return; + } + final boolean packed = blockStates.get(DATA_KEY) instanceof LongArrayBinaryTag; + + if (packed) { + if (this.packedBudget == 0) { + return; + } + this.packedBudget--; + this.packedVerified++; + } else { + if (this.flatBudget == 0) { + return; + } + this.flatBudget--; + this.flatVerified++; + } + + final PaletteData data = SectionCodec.decode( + blockStates, this.resolver, BLOCK_ENTRIES, Palette.BLOCK_PALETTE_MIN_BITS); + final int[] values = data.unpack(); + boolean allEqual = true; + boolean allAir = true; + + for (int value : values) { + allEqual &= value == values[0]; + allAir &= value == this.airId; + } + + switch (sectionClass) { + case EMPTY -> { + if (!allAir) { + record(sectionClass, "its entries are not all air"); + } + } + case UNIFORM -> { + if (!allEqual) { + record(sectionClass, "its entries are not all the same"); + } else if (allAir) { + record(sectionClass, "its entries are all air"); + } + } + case MIXED -> { + // Not a defect. A palette of several entries whose indices all point at one of + // them is what a world looks like after a build was torn down again, and the + // class documentation states that such a section is counted as mixed. Counting + // how often it happens turns the stated lower bound into a measured one. + if (allAir) { + this.mixedButAir++; + this.mixedButUniform++; + } else if (allEqual) { + this.mixedButUniform++; + } + } + case NO_BLOCK_STATES -> throw new IllegalStateException("A section without blocks is not verified"); + } + } + + /** + * Records a section whose content contradicts the class it was sorted into. + * + * @param sectionClass the class the census sorted the section into + * @param reason what the unpacked entries say instead + */ + private void record(SectionClass sectionClass, String reason) { + this.mismatches++; + + if (this.firstMismatch == null) { + this.firstMismatch = "a section was counted as " + sectionClass + " although " + reason; + } + } + + /** + * Returns the amount of sections whose content contradicted their class. + * + * @return the amount of mismatches + */ + private int mismatches() { + return this.mismatches; + } + + /** + * Returns the description of the first mismatch, which names what went wrong. + * + * @return the description or null if every verified section agreed with its class + */ + private @Nullable String firstMismatch() { + return this.firstMismatch; + } + } + + /** + * Resolves palette entries into ids by interning them, without asking a block registry. + *

+ * The verification needs identity of palette entries and nothing else, so an id that is unique + * per name and property set answers every question it asks. Building the ids this way keeps the + * whole census free of a running server, which is what lets it run inside an ordinary test task. + *

+ */ + private static final class InterningResolver implements PaletteEntryResolver { + + private final Map ids = new HashMap<>(); + private final List names = new ArrayList<>(); + + /** + * {@inheritDoc} + */ + @Override + public int toId(String name, @Nullable CompoundBinaryTag properties) { + final String key = properties == null || properties.size() == 0 ? name : name + describe(properties); + final Integer known = this.ids.get(key); + + if (known != null) { + return known; + } + final int id = this.names.size(); + this.names.add(name); + this.ids.put(key, id); + return id; + } + + /** + * {@inheritDoc} + */ + @Override + public CompoundBinaryTag toEntry(int id) { + return CompoundBinaryTag.builder().putString(NAME_KEY, this.names.get(id)).build(); + } + + /** + * Renders the properties of a palette entry into a stable key. + * + * @param properties the properties of the entry + * @return the key of the properties + */ + private static String describe(CompoundBinaryTag properties) { + final Map sorted = new TreeMap<>(); + + for (Map.Entry property : properties) { + final BinaryTag value = property.getValue(); + sorted.put(property.getKey(), + value instanceof StringBinaryTag string ? string.value() : value.toString()); + } + return sorted.toString(); + } + } + + /** + * The class a stored section belongs to. + */ + private enum SectionClass { + + /** + * The section stores a palette of one entry and that entry is air. + */ + EMPTY, + + /** + * The section stores a palette of one entry and that entry is not air. + */ + UNIFORM, + + /** + * The section stores a palette of more than one entry. + */ + MIXED, + + /** + * The section stores no block palette at all and therefore holds no blocks. + */ + NO_BLOCK_STATES + } + + /** + * The result of a census. + * + * @param readFiles the amount of region files that were read + * @param regionFiles the amount of region files the directory holds + * @param chunks the amount of chunks that were read + * @param chunksWithoutSections the amount of read chunks that resolved no section at all + * @param sections the amount of sections those chunks store + * @param empty the amount of sections that hold nothing but air + * @param uniform the amount of sections that hold a single block that is not air + * @param mixed the amount of sections that store more than one palette entry + * @param withoutBlockStates the amount of sections that store no block palette at all + * @param packedEmpty the amount of sections counted as air only that still store packed data + * @param totalByY the amount of sections per section height + * @param emptyByY the amount of empty sections per section height + * @param nonAirNames every block name other than air, with the amount of palettes holding it + * @param statuses the generation status of the read chunks, with the amount of chunks + * @param verification the result of re-reading a sample through the decoder of the loader + */ + private record Census(int readFiles, int regionFiles, int chunks, int chunksWithoutSections, int sections, + int empty, int uniform, int mixed, int withoutBlockStates, int packedEmpty, + int[] totalByY, int[] emptyByY, Map nonAirNames, + Map statuses, Verification verification) { + } +} diff --git a/falco-benchmarks/src/test/java/net/onelitefeather/falco/benchmark/instance/FalcoChunkEquivalenceTest.java b/falco-benchmarks/src/test/java/net/onelitefeather/falco/benchmark/instance/FalcoChunkEquivalenceTest.java new file mode 100644 index 0000000..435054e --- /dev/null +++ b/falco-benchmarks/src/test/java/net/onelitefeather/falco/benchmark/instance/FalcoChunkEquivalenceTest.java @@ -0,0 +1,605 @@ +package net.onelitefeather.falco.benchmark.instance; + +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.DynamicChunk; +import net.minestom.server.instance.Instance; +import net.minestom.server.instance.InstanceContainer; +import net.minestom.server.instance.block.Block; +import net.minestom.server.instance.heightmap.Heightmap; +import net.onelitefeather.falco.benchmark.support.BenchmarkConstants; +import net.onelitefeather.falco.benchmark.support.MinestomChunks; +import net.onelitefeather.falco.benchmark.support.MinestomChunks.FillShape; +import net.onelitefeather.falco.instance.FalcoChunk; +import net.onelitefeather.falco.instance.FalcoInstance; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.Arguments; +import org.junit.jupiter.params.provider.MethodSource; + +import java.util.Arrays; +import java.util.BitSet; +import java.util.Objects; +import java.util.Random; +import java.util.stream.Stream; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertInstanceOf; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Pins down that the chunk of Falco is indistinguishable from the chunk of Minestom on every + * operation {@link ChunkComparisonBenchmark} measures, so the control of that benchmark also falls + * during an ordinary {@code ./gradlew check} instead of only during a JMH run. + *

+ * This test was written while {@code FalcoChunk} still extended {@code DynamicChunk}, added no + * field and overrode nothing but {@code copy} and two widened lifecycle hooks. The equality it + * asserts was a structural consequence of that inheritance, and the test existed to catch the day + * the structure changed. That day has come: since stage 1 of the block storage work + * {@code FalcoChunk} extends {@code Chunk}, keeps its blocks behind a {@code BlockStorage} field + * and overrides {@code setBlock}, {@code getBlock} and both heightmap accessors itself. + *

+ *

+ * The change makes this file more important, not less. The equality is now a property of two + * implementations that no longer share a line of code — {@code SectionBlockStorage} reproduces the + * layout of {@code DynamicChunk} on purpose, but reproducing it is a claim somebody has to check + * rather than something the compiler can enforce. Every comparison this module publishes rests on + * that claim, so it is asserted here position by position and heightmap by heightmap instead of + * being inferred from a class hierarchy that no longer exists. + *

+ *

+ * The benchmark takes the same check in its {@code @Setup} and aborts the trial when it fails. That + * is the right place for it but the wrong moment: a JMH run happens when somebody asks for numbers, + * which can be weeks after the change that broke the equality, and it happens outside continuous + * integration. A test brings the same failure forward to the commit that caused it. + *

+ * + *

What this test covers that the benchmark cannot

+ *

+ * Three things. It proves that the comparison can fail at all — a check that never rejects anything + * proves nothing, so two deliberately different chunks are fed to the very same comparison and it + * has to reject them. It proves that the two arms are still two different types, which is the one + * defect that would make every other assertion pass while the whole comparison degenerated into a + * type against itself. And it proves that the equality does not depend on the seed, by running one + * shape a second time from an unrelated one. + *

+ * + *

Why the operations are driven exactly as the benchmark drives them

+ *

+ * The point of this test is not that two chunks can be filled identically — the fixture does that + * and has its own guarantees. The point is that they stay identical through the four operations the + * benchmark measures, in the order and with the locks the benchmark uses. A scattered write batch + * that is faithful here but not there would leave the benchmark measuring an unverified state. + * The batch size, the block rotation and the seed are therefore taken from the same constants, and + * the scattered positions are drawn distinct for the same reason: a repeated position would let a + * later write of the batch delete the block an earlier one placed, and the exact state count both + * sides are checked against would stop being reachable. + *

+ * + *

Why there is no test extension

+ *

+ * The light module starts its server through {@code MicrotusExtension} because its fixtures need + * nothing else. Here the server is only one of four things that have to be identical on both sides, + * and the other three — the instances, the chunks and their content — come from + * {@code MinestomChunks}. Letting the same fixture start the server keeps this test and the + * benchmark on one code path instead of two, which is the only way the test can claim to guard what + * the benchmark measures. + *

+ * + *

Why a chunk with an empty top is tested separately

+ *

+ * Because the fixtures above cannot reach the code that decides it. Every one of them fills the + * chunk from its floor to its build limit, which leaves no section empty, and a scan for the highest + * non-empty section on such a chunk stops at the first section it looks at whatever it does + * afterwards. Since stage 2 {@code FalcoChunk} no longer starts its heightmap refresh from + * {@code Heightmap#getHighestBlockSection(Chunk)} but from a copy of it that reads the storage + * instead of {@code Chunk#getSection(int)}, and a copy is exactly the kind of code that has to be + * run against its original on the inputs where the two could differ — a chunk whose top is empty, + * which is every chunk of a real world. + * {@link #testTheCopiedHighestSectionScanAgreesWithMinestom(String, int[], int)} supplies those + * inputs, compares the two start heights on them, and rebuilds both heightmaps from the height each + * arm computed for itself. + *

+ *

+ * It rebuilds them through {@link #refreshHeightmaps(Chunk)} rather than through the chunk, and that + * is a limitation of Minestom rather than a shortcut. {@code calculateFullHeightmap} is private on + * both arms; the only public way to reach it is {@code Chunk#invalidate()} followed by a write, and + * that path recomputes nothing, because it ends in {@code Heightmap#refresh(int)} whose first line + * returns unless the heightmap's own {@code needsRefresh} is still set — a flag {@code invalidate()} + * does not touch and nothing public can set again. A full recompute therefore happens exactly once + * in the life of a chunk, on its first write, and a test that drove it that way would be asserting + * against heightmaps that were never rebuilt. The per column {@code Heightmap#refresh(int, int, int)} + * carries no such guard, which is why both this test and the benchmark reproduce the body instead of + * triggering it. + *

+ * + *

Running it

+ * 
{@code
+ * ./gradlew :falco-benchmarks:test --tests "*FalcoChunkEquivalenceTest"
+ * }
+ * + * @author TheMeinerLP + * @version 1.2.0 + * @since 0.4.0 + */ +class FalcoChunkEquivalenceTest { + + /** + * The amounts of distinct block states a compared chunk is filled with. + * The axis of {@link ChunkComparisonBenchmark}, repeated so the test covers every point the + * benchmark will later report a number for. + */ + private static final int[] DISTINCT_STATES = {1, 2, 16, 64, 256, 1024}; + + /** + * The amount of distinct positions the scattered batch touches. + * The batch size of {@link ChunkComparisonBenchmark#SCATTER_COUNT}. + */ + private static final int SCATTER_COUNT = ChunkComparisonBenchmark.SCATTER_COUNT; + + /** + * The seed the compared chunks are built from, so a failure can be reproduced. + * The seed of the module, which is the one the benchmark fills with as well. + */ + private static final long SEED = BenchmarkConstants.SEED; + + /** + * A second, unrelated seed, so the equality can be shown not to depend on the first one. + */ + private static final long ALTERNATE_SEED = 20260731L; + + /** + * The chunk position the compared chunks are created at. + */ + private static final int CHUNK_POSITION = 0; + + /** + * The floor of the world the chunks of this test live in. + */ + private static final int OVERWORLD_MIN_Y = -64; + + /** + * The build limit of the world the chunks of this test live in. + */ + private static final int OVERWORLD_MAX_Y = 320; + + private InstanceContainer container; + private FalcoInstance falco; + + /** + * Builds the two instances the compared chunks come from. + */ + @BeforeEach + void createInstances() { + MinestomChunks.ensureServer(); + this.container = MinestomChunks.newContainer(); + this.falco = MinestomChunks.newFalcoInstance(); + } + + /** + * Releases the two instances so they do not leak into the following test. + */ + @AfterEach + void releaseInstances() { + MinestomChunks.release(this.container); + MinestomChunks.release(this.falco); + } + + /** + * Returns every combination of state count and arrangement the benchmark measures. + * + * @return the arguments of {@link #testBothChunksSurviveEveryOperationIdentically(int, FillShape)} + */ + static Stream fixtures() { + return Stream.of(FillShape.values()) + .flatMap(shape -> Arrays.stream(DISTINCT_STATES) + .mapToObj(states -> Arguments.of(states, shape))); + } + + @ParameterizedTest(name = "{1} with {0} distinct states") + @MethodSource("fixtures") + void testBothChunksSurviveEveryOperationIdentically(int distinctStates, FillShape shape) { + Chunk minestomChunk = MinestomChunks.newChunk(this.container, CHUNK_POSITION, CHUNK_POSITION); + Chunk falcoChunk = MinestomChunks.newChunk(this.falco, CHUNK_POSITION, CHUNK_POSITION); + + // The arms have to be two different types before anything else is worth asserting; a + // comparison of a type against itself would pass every check below without measuring one. + // The two are siblings under Chunk since stage 1, so the first assertion already excludes a + // FalcoChunk; the second stays because it names what is being excluded and why. + assertInstanceOf(DynamicChunk.class, minestomChunk); + assertFalse(minestomChunk instanceof FalcoChunk, + "the container has to hand out a plain DynamicChunk, otherwise the two arms are one"); + assertInstanceOf(FalcoChunk.class, falcoChunk); + + MinestomChunks.fill(minestomChunk, distinctStates, shape, SEED); + MinestomChunks.fill(falcoChunk, distinctStates, shape, SEED); + MinestomChunks.assertSameBlocks(minestomChunk, falcoChunk); + + // A chunk of nothing but air answers every read from an empty palette and would compare + // equal no matter what either type does. The fixture throws on it, so reaching this line + // already proves the fill took; the count is the stronger statement that it took the + // parameter as well. + MinestomChunks.assertNotAllAir(minestomChunk); + MinestomChunks.assertNotAllAir(falcoChunk); + + int[] scatterX = new int[SCATTER_COUNT]; + int[] scatterY = new int[SCATTER_COUNT]; + int[] scatterZ = new int[SCATTER_COUNT]; + Block[] scatterBlocks = new Block[SCATTER_COUNT]; + buildScatter(minestomChunk, distinctStates, scatterX, scatterY, scatterZ, scatterBlocks); + + writeScatter(minestomChunk, scatterX, scatterY, scatterZ, scatterBlocks); + writeScatter(falcoChunk, scatterX, scatterY, scatterZ, scatterBlocks); + MinestomChunks.assertSameBlocks(minestomChunk, falcoChunk); + + assertEquals(distinctStates, MinestomChunks.countDistinctStates(minestomChunk), + "the Minestom chunk holds a different amount of distinct states than the axis asked for"); + assertEquals(distinctStates, MinestomChunks.countDistinctStates(falcoChunk), + "the Falco chunk holds a different amount of distinct states than the axis asked for"); + assertEquals(MinestomChunks.countNonAir(minestomChunk), MinestomChunks.countNonAir(falcoChunk)); + + assertEquals(readScatter(minestomChunk, scatterX, scatterY, scatterZ), + readScatter(falcoChunk, scatterX, scatterY, scatterZ), + "the scattered reads of the two chunks disagree"); + + // Both heightmaps are thrown away and recomputed from the palettes, which is the operation + // the benchmark measures and the one place where two chunks holding the same blocks could + // still end up disagreeing, because a heightmap is derived state. + assertEquals(refreshHeightmaps(minestomChunk), refreshHeightmaps(falcoChunk), + "the refreshed heightmaps of the two chunks disagree"); + MinestomChunks.assertSameBlocks(minestomChunk, falcoChunk); + + Chunk minestomCopy = copy(minestomChunk, this.container); + Chunk falcoCopy = copy(falcoChunk, this.falco); + + assertInstanceOf(FalcoChunk.class, falcoCopy, + "a copy of a FalcoChunk has to stay a FalcoChunk, otherwise its instance can never unload it"); + assertFalse(minestomCopy instanceof FalcoChunk); + + // A copy that is faithful on both sides is what the copy arm of the benchmark assumes; a + // copy that quietly dropped content would make that arm the fastest of the whole grid. + MinestomChunks.assertSameBlocks(minestomChunk, minestomCopy); + MinestomChunks.assertSameBlocks(falcoChunk, falcoCopy); + MinestomChunks.assertSameBlocks(minestomCopy, falcoCopy); + } + + @Test + void testTheComparisonRejectsTwoChunksThatDiffer() { + // Without this the whole test class could be passing because the comparison accepts + // everything. Two chunks of the same shape and the same state count, filled from two + // different seeds, have to be rejected by the very method every other case relies on. + Chunk first = MinestomChunks.newChunk(this.container, CHUNK_POSITION, CHUNK_POSITION); + Chunk second = MinestomChunks.newChunk(this.falco, CHUNK_POSITION, CHUNK_POSITION); + + MinestomChunks.fill(first, 16, FillShape.RANDOM_RUNS, SEED); + MinestomChunks.fill(second, 16, FillShape.RANDOM_RUNS, ALTERNATE_SEED); + + assertThrows(IllegalStateException.class, () -> MinestomChunks.assertSameBlocks(first, second), + "the comparison accepted two chunks built from different seeds, so it proves nothing"); + } + + /** + * Returns the fixtures {@link #testTheCopiedHighestSectionScanAgreesWithMinestom(String, int[], int)} + * runs, as a name, the world heights that hold a full layer of blocks, and the height the scan + * has to start at. + *

+ * Every expected start height is the arithmetic of {@code Heightmap#getHighestBlockSection} + * written out by hand for that fixture rather than taken from a run: the build limit of the + * overworld is {@value #OVERWORLD_MAX_Y}, and the scan subtracts one section of + * {@code 16} for every section above the highest one holding a block. The floor layer leaves + * {@code 23} sections empty above it and therefore starts at {@code -48}; the island at + * {@code 200} sits in the section spanning {@code 192} to {@code 207} and leaves {@code 7}, + * therefore {@code 208}; a layer at the build limit leaves none. The untouched chunk is the + * degenerate end where every section is empty and the scan walks the whole chunk down to its + * floor. + *

+ *

+ * The last two fixtures differ in nothing but a layer on the floor, far below the island. That + * pair is what separates a scan that reports the highest non-empty section from one that reports + * any non-empty section: an implementation walking upwards, or one breaking on the wrong end, + * agrees with Minestom on every other fixture here and disagrees on that one. + *

+ * + * @return the arguments of {@link #testTheCopiedHighestSectionScanAgreesWithMinestom(String, int[], int)} + */ + static Stream emptyTopFixtures() { + return Stream.of( + Arguments.of("an untouched chunk", new int[0], OVERWORLD_MIN_Y), + Arguments.of("a layer on the floor", new int[]{-64}, -48), + Arguments.of("a layer at the build limit", new int[]{319}, 320), + Arguments.of("an island at 200 to 203", new int[]{200, 201, 202, 203}, 208), + Arguments.of("an island at 200 to 203 over a floor", new int[]{-64, 200, 201, 202, 203}, 208) + ); + } + + @ParameterizedTest(name = "{0}") + @MethodSource("emptyTopFixtures") + void testTheCopiedHighestSectionScanAgreesWithMinestom(String name, int[] filledLayers, int expectedStartY) { + Chunk minestomChunk = MinestomChunks.newChunk(this.container, CHUNK_POSITION, CHUNK_POSITION); + Chunk falcoChunk = MinestomChunks.newChunk(this.falco, CHUNK_POSITION, CHUNK_POSITION); + FalcoChunk typedFalcoChunk = assertInstanceOf(FalcoChunk.class, falcoChunk); + + // The expected start heights are literals derived from these two bounds. A dimension whose + // extent changed would make every one of them wrong while the comparison of the two arms + // still passed, so the bounds are asserted rather than assumed. + assertEquals(OVERWORLD_MIN_Y, minestomChunk.getMinSection() * Chunk.CHUNK_SECTION_SIZE, + "the fixture no longer starts at the floor the expected start heights were computed for"); + assertEquals(OVERWORLD_MAX_Y, minestomChunk.getMaxSection() * Chunk.CHUNK_SECTION_SIZE, + "the fixture no longer ends at the build limit the expected start heights were computed for"); + + final Block block = MinestomChunks.distinctBlocks(1)[0]; + fillLayers(minestomChunk, filledLayers, block); + fillLayers(falcoChunk, filledLayers, block); + + // Both start heights are taken before the block walk, because the walk reaches the sections + // of the Falco chunk through Chunk#getSections() and creates every one of them. The scan + // under test runs on the storage as the chunk keeps it, which for the empty part of these + // fixtures is a shared section rather than one of its own. + minestomChunk.lockReadLock(); + try { + assertEquals(expectedStartY, Heightmap.getHighestBlockSection(minestomChunk), + "Minestom does not start its scan where the fixture says it has to"); + } finally { + minestomChunk.unlockReadLock(); + } + falcoChunk.lockReadLock(); + try { + assertEquals(expectedStartY, typedFalcoChunk.highestBlockSection(), + "the copied scan of FalcoChunk starts at a different height than Minestom's"); + } finally { + falcoChunk.unlockReadLock(); + } + MinestomChunks.assertSameBlocks(minestomChunk, falcoChunk); + + // The scan is compared above and used here. Both chunks rebuild their heightmaps column by + // column from the start height their own arm computed, which is what turns a wrong start + // height into a wrong heightmap rather than only into a wrong number: a scan beginning below + // the top of the fixture cannot see it and reports the floor for every column. + assertEquals(refreshHeightmaps(minestomChunk), refreshHeightmaps(falcoChunk), + "the heightmaps rebuilt from the two start heights disagree"); + MinestomChunks.assertSameBlocks(minestomChunk, falcoChunk); + + // Equality alone would also hold if both chunks had missed the island and reported their + // floor, so the height itself is pinned. The world surface heightmap is the one asked, + // because its predicate is "not air" and therefore says nothing about which block the + // fixture happened to draw; an empty column reports the minimum height of a heightmap, + // which Minestom defines as one below the floor of the world. + final int expectedSurface = filledLayers.length == 0 + ? OVERWORLD_MIN_Y - 1 + : Arrays.stream(filledLayers).max().orElseThrow(); + assertEquals(expectedSurface, minestomChunk.worldSurfaceHeightmap().getHeight(0, 0), + "the refreshed Minestom heightmap did not find the top of the fixture"); + assertEquals(expectedSurface, falcoChunk.worldSurfaceHeightmap().getHeight(0, 0), + "the refreshed Falco heightmap did not find the top of the fixture"); + } + + @Test + void testTheEqualityDoesNotDependOnTheSeed() { + Chunk minestomChunk = MinestomChunks.newChunk(this.container, CHUNK_POSITION, CHUNK_POSITION); + Chunk falcoChunk = MinestomChunks.newChunk(this.falco, CHUNK_POSITION, CHUNK_POSITION); + + MinestomChunks.fill(minestomChunk, 64, FillShape.RANDOM_RUNS, ALTERNATE_SEED); + MinestomChunks.fill(falcoChunk, 64, FillShape.RANDOM_RUNS, ALTERNATE_SEED); + + MinestomChunks.assertSameBlocks(minestomChunk, falcoChunk); + assertEquals(64, MinestomChunks.countDistinctStates(minestomChunk)); + } + + @Test + void testAChunkThatStayedAirIsRejected() { + // The anti tautology check of the whole module. An empty chunk holds a palette with no + // backing array, so every measurement on it collapses to object headers and every + // comparison on it succeeds. It has to be refused rather than measured. + Chunk untouched = MinestomChunks.newChunk(this.container, CHUNK_POSITION, CHUNK_POSITION); + + assertEquals(0, MinestomChunks.countNonAir(untouched)); + assertThrows(IllegalStateException.class, () -> MinestomChunks.assertNotAllAir(untouched)); + + // Two empty chunks compare equal, which is the trap: the comparison is not what protects + // this module against an empty fixture, the air check is. + Chunk otherUntouched = MinestomChunks.newChunk(this.falco, CHUNK_POSITION, CHUNK_POSITION); + MinestomChunks.assertSameBlocks(untouched, otherUntouched); + } + + @Test + void testAFillWithoutAnyStateIsRefused() { + Chunk chunk = MinestomChunks.newChunk(this.container, CHUNK_POSITION, CHUNK_POSITION); + + assertThrows(IllegalArgumentException.class, + () -> MinestomChunks.fill(chunk, 0, FillShape.UNIFORM, SEED)); + assertThrows(IllegalArgumentException.class, + () -> MinestomChunks.fill(chunk, MinestomChunks.blockCount(chunk) + 1, FillShape.UNIFORM, SEED)); + } + + @Test + void testTheRegistryStillCarriesTheLargestStateCount() { + // The largest point of the axis is above the amount of distinct blocks the pinned build + // offers, so the fixture falls back to further states of the same blocks there. That + // fallback is a documented property of the measurement, not an accident, and a Minestom + // bump that removed it or widened it should be noticed here rather than in a curve. + assertTrue(MinestomChunks.availableBlocks() > 0); + assertTrue(MinestomChunks.availableStates() >= DISTINCT_STATES[DISTINCT_STATES.length - 1], + "the block registry no longer holds enough states for the largest point of the axis"); + assertEquals(DISTINCT_STATES[DISTINCT_STATES.length - 1], + MinestomChunks.distinctBlocks(DISTINCT_STATES[DISTINCT_STATES.length - 1]).length); + } + + /** + * Draws the distinct positions and the blocks of the scattered batch. + * + * @param chunk the chunk the positions are drawn inside of + * @param distinctStates the amount of distinct block states the batch draws from + * @param scatterX the block X of every position, filled by this method + * @param scatterY the block Y of every position, filled by this method + * @param scatterZ the block Z of every position, filled by this method + * @param scatterBlocks the block of every position, filled by this method + */ + private static void buildScatter(Chunk chunk, int distinctStates, int[] scatterX, int[] scatterY, + int[] scatterZ, Block[] scatterBlocks) { + final int minY = chunk.getMinSection() * Chunk.CHUNK_SECTION_SIZE; + final int height = (chunk.getMaxSection() - chunk.getMinSection()) * Chunk.CHUNK_SECTION_SIZE; + final Block[] blocks = MinestomChunks.distinctBlocks(distinctStates); + final Random random = new Random(SEED); + final BitSet taken = new BitSet(Chunk.CHUNK_SIZE_X * Chunk.CHUNK_SIZE_Z * height); + + for (int index = 0; index < SCATTER_COUNT; index++) { + int x; + int y; + int z; + int packed; + + do { + x = random.nextInt(Chunk.CHUNK_SIZE_X); + y = random.nextInt(height); + z = random.nextInt(Chunk.CHUNK_SIZE_Z); + packed = (y * Chunk.CHUNK_SIZE_Z + z) * Chunk.CHUNK_SIZE_X + x; + } while (taken.get(packed)); + + taken.set(packed); + scatterX[index] = x; + scatterY[index] = minY + y; + scatterZ[index] = z; + scatterBlocks[index] = blocks[index % blocks.length]; + } + } + + /** + * Writes a full horizontal layer of one block into a chunk, for every height it is given. + *

+ * A whole layer rather than a single block, because the scan under test asks a palette for its + * count and a section that holds one block answers the same as one that holds two hundred and + * fifty six. The layer is what makes the resulting heightmap worth comparing: it gives every + * column of the chunk the same top, so a column that came out wrong is a column the scan missed + * rather than a column the fixture never filled. + *

+ * + * @param chunk the chunk to write into + * @param layers the world heights that receive a full layer + * @param block the block every layer is written with + */ + private static void fillLayers(Chunk chunk, int[] layers, Block block) { + chunk.lockWriteLock(); + try { + for (int y : layers) { + for (int x = 0; x < Chunk.CHUNK_SIZE_X; x++) { + for (int z = 0; z < Chunk.CHUNK_SIZE_Z; z++) { + chunk.setBlock(x, y, z, block); + } + } + } + } finally { + chunk.unlockWriteLock(); + } + } + + /** + * Writes the scattered batch into a chunk, with the write lock the setter demands. + * + * @param chunk the chunk to write into + * @param scatterX the block X of every position + * @param scatterY the block Y of every position + * @param scatterZ the block Z of every position + * @param scatterBlocks the block of every position + */ + private static void writeScatter(Chunk chunk, int[] scatterX, int[] scatterY, int[] scatterZ, + Block[] scatterBlocks) { + chunk.lockWriteLock(); + try { + for (int index = 0; index < SCATTER_COUNT; index++) { + chunk.setBlock(scatterX[index], scatterY[index], scatterZ[index], scatterBlocks[index]); + } + } finally { + chunk.unlockWriteLock(); + } + } + + /** + * Reads the scattered batch from a chunk and sums the state ids it finds. + * + * @param chunk the chunk to read from + * @param scatterX the block X of every position + * @param scatterY the block Y of every position + * @param scatterZ the block Z of every position + * @return the sum of the read state ids + */ + private static int readScatter(Chunk chunk, int[] scatterX, int[] scatterY, int[] scatterZ) { + int sum = 0; + + chunk.lockReadLock(); + try { + for (int index = 0; index < SCATTER_COUNT; index++) { + final Block block = chunk.getBlock(scatterX[index], scatterY[index], scatterZ[index], + Block.Getter.Condition.NONE); + sum += Objects.requireNonNullElse(block, Block.AIR).stateId(); + } + } finally { + chunk.unlockReadLock(); + } + return sum; + } + + /** + * Recomputes both heightmaps of a chunk from its palettes and sums the heights that come out. + *

+ * The same reproduction of the private {@code calculateFullHeightmap} of the chunk it is handed + * that the benchmark measures, through the per column {@code Heightmap#refresh(int, int, int)} + * which carries no refresh guard and therefore performs the scan every time it is called. + *

+ *

+ * The start of the scan is taken from the arm's own chunk, exactly as the benchmark takes it: + * {@code DynamicChunk} starts from {@code Heightmap#getHighestBlockSection(Chunk)}, + * {@code FalcoChunk} from {@link FalcoChunk#highestBlockSection()}. Running the static helper on + * both arms would compare Minestom's scan against itself and would leave the copy inside + * {@code FalcoChunk} untested by every fixture of this class. + *

+ * + * @param chunk the chunk to refresh the heightmaps of + * @return the sum of the refreshed heights of both heightmaps + */ + private static int refreshHeightmaps(Chunk chunk) { + int sum = 0; + + chunk.lockWriteLock(); + try { + final int startY = chunk instanceof FalcoChunk falcoChunk + ? falcoChunk.highestBlockSection() + : Heightmap.getHighestBlockSection(chunk); + final Heightmap motionBlocking = chunk.motionBlockingHeightmap(); + final Heightmap worldSurface = chunk.worldSurfaceHeightmap(); + + for (int x = 0; x < Chunk.CHUNK_SIZE_X; x++) { + for (int z = 0; z < Chunk.CHUNK_SIZE_Z; z++) { + motionBlocking.refresh(x, z, startY); + worldSurface.refresh(x, z, startY); + } + } + for (int x = 0; x < Chunk.CHUNK_SIZE_X; x++) { + for (int z = 0; z < Chunk.CHUNK_SIZE_Z; z++) { + sum += motionBlocking.getHeight(x, z) + worldSurface.getHeight(x, z); + } + } + } finally { + chunk.unlockWriteLock(); + } + return sum; + } + + /** + * Copies a chunk to a neighbouring position, with the read lock the copy demands. + * + * @param chunk the chunk to copy + * @param instance the instance the copy is created for + * @return the created copy + */ + private static Chunk copy(Chunk chunk, Instance instance) { + chunk.lockReadLock(); + try { + return chunk.copy(instance, CHUNK_POSITION + 1, CHUNK_POSITION); + } finally { + chunk.unlockReadLock(); + } + } +} diff --git a/falco-benchmarks/src/test/java/net/onelitefeather/falco/benchmark/instance/JolMeasurement.java b/falco-benchmarks/src/test/java/net/onelitefeather/falco/benchmark/instance/JolMeasurement.java new file mode 100644 index 0000000..b0556c5 --- /dev/null +++ b/falco-benchmarks/src/test/java/net/onelitefeather/falco/benchmark/instance/JolMeasurement.java @@ -0,0 +1,346 @@ +package net.onelitefeather.falco.benchmark.instance; + +import org.junit.jupiter.api.Assumptions; +import org.openjdk.jol.vm.VM; +import org.openjdk.jol.vm.VirtualMachine; + +import java.lang.instrument.Instrumentation; +import java.lang.reflect.Field; +import java.util.Locale; + +import static org.junit.jupiter.api.Assertions.fail; + +/** + * The {@link JolMeasurement} class establishes, once per JVM, in which of its several modes JOL is + * actually running, and refuses to let a footprint table be printed before that question is answered. + *

+ * It exists because JOL does not have one way of answering how large an object is, it has two, and it + * picks between them at runtime without the caller being told. When {@code org.openjdk.jol.vm.VM} is + * first touched it tries to attach an instrumentation agent to the running JVM; if that works, every + * size JOL reports afterwards comes from {@code Instrumentation#getObjectSize}, which is the JVM + * stating the truth about its own heap. If it does not work, JOL prints one line to standard output + * and then computes every size from a layout model built out of field offsets, alignment and a header + * size it guessed — and it keeps answering, with numbers that look exactly like measurements. A + * project whose architecture decisions rest on those numbers cannot afford to find that out by + * reading log lines. + *

+ * + *

The bug this class was written for

+ *

+ * There is a second, sharper edge on the same knife. A graph walk that reaches a record class inside + * {@code java.base} dies on JDK 25 with {@code Cannot get the field offset}, because + * {@code Unsafe#objectFieldOffset} refuses record classes, and JOL only survives it when + * {@code jol.magicFieldOffset} is set. That option is read exactly once, in the class initialiser of + * {@code HotspotUnsafe}, which runs the first time any code in the JVM asks JOL for anything. + *

+ *

+ * {@code ChunkFootprintTest} used to set the property from its own static initialiser. That works if + * and only if {@code ChunkFootprintTest} is the first class in the test JVM to touch JOL. It shares + * that JVM with {@code PaletteFootprintTest} and {@code EmptySectionCensusTest}, which also walk + * object graphs, and the order in which JUnit runs test classes is not specified: it falls out of + * classpath scanning, which follows directory order on disk and changes when the class files are + * rewritten. Whenever one of the other two ran first, JOL had already cached + * {@code magicFieldOffset == false} and all three measurements of {@code ChunkFootprintTest} failed; + * whenever it ran first, they passed. Same code, same machine, two different outcomes — a flaky + * measurement, which is worse than a red one, because the green runs invited people to quote numbers + * from a mechanism nobody had checked. + *

+ *

+ * The fix is that the two JOL options are now JVM arguments of the test task, set by + * {@code falco-benchmarks/build.gradle.kts} before a single class is loaded, so no ordering exists + * that can defeat them. This class is the second half of that fix: it reads back what JOL actually + * decided and makes the tests state it or stop. + *

+ * + *

Why the mode is read out of JOL rather than assumed

+ *

+ * JOL exposes no API for either question. {@code VirtualMachine} has {@code details()}, which + * describes the compressed reference layout, and nothing that says where a size came from. The two + * facts live in fields of the package private {@code HotspotUnsafe}: {@code instrumentation}, which is + * null exactly when sizes are modelled, and {@code MAGIC_FIELD_OFFSET}, which is the value the option + * had when JOL initialised rather than the value the system property carries now. Reading them + * reflectively is a coupling to an implementation detail, and it is deliberately the loud kind: if a + * future JOL renames or removes either field, {@link Mode#UNKNOWN} is reported and every measurement + * stops with an assumption instead of continuing with an unproven mechanism. + *

+ * + *

What is checked, and what happens when it fails

+ *

+ * Two different kinds of failure deserve two different outcomes. A JVM that JOL could not attach an + * instrumentation agent to is an environment: another JDK, a hardened container, a future release + * that has switched dynamic agent loading off. The measurement is impossible there, so + * {@link #require()} stops with an {@link Assumptions assumption} that names the mode it found. The + * missing number stays visible as a skipped test rather than turning into a modelled one. + *

+ *

+ * A JVM whose JOL saw {@code magicFieldOffset == false} is not an environment, it is this build having + * lost its own flag, and it is the exact regression that made these tests flaky. That one fails, + * loudly, and the message names the line of the build file that has to come back. + *

+ * + *

Running it

+ *

+ * Nothing here is measured; it only guards and describes. It runs inside every JOL test of this + * module: + *

+ * 
{@code
+ * ./gradlew :falco-benchmarks:test -i
+ * ./gradlew :falco-benchmarks:test -Pfalco.compactHeaders -i
+ * }
+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +final class JolMeasurement { + + /** + * The JOL option that lets a graph walk read a field of a record class of {@code java.base}. + */ + private static final String MAGIC_FIELD_OFFSET = "jol.magicFieldOffset"; + + /** + * The name of the field of {@code HotspotUnsafe} that holds the instrumentation agent. + */ + private static final String INSTRUMENTATION_FIELD = "instrumentation"; + + /** + * The name of the field of {@code HotspotUnsafe} that says whether the Serviceability Agent + * attached, which decides whether addresses are read or guessed. + */ + private static final String ACCURATE_FIELD = "isAccurate"; + + /** + * The name of the field of {@code HotspotUnsafe} that holds the value {@link #MAGIC_FIELD_OFFSET} + * had when JOL initialised. + */ + private static final String MAGIC_FIELD_OFFSET_FIELD = "MAGIC_FIELD_OFFSET"; + + /** + * Where the byte figures of a JOL table come from. + */ + enum Mode { + + /** + * Every size is {@code Instrumentation#getObjectSize} of the running JVM, which is the only + * mode in which a byte figure of this module is a measurement. + */ + INSTRUMENTATION("the instrumentation agent"), + + /** + * JOL could not attach an agent and computes every size from field offsets, the object + * alignment and a guessed header size. The numbers are a model of the JVM, not a reading of + * it, and no table of this module may be published from them. + */ + LAYOUT_MODEL("a layout model, which is a computation and not a measurement"), + + /** + * JOL no longer exposes which of the two it used, so nothing can be said about the numbers. + */ + UNKNOWN("a mode this build could not determine"); + + /** + * What the mode means, phrased so it can be printed in a table header. + */ + private final String description; + + /** + * Creates a mode. + * + * @param description what the mode means in a table header + */ + Mode(String description) { + this.description = description; + } + + /** + * Returns what the mode means, phrased for a table header. + * + * @return the description of the mode + */ + String description() { + return this.description; + } + } + + /** + * Blocks the creation of an instance because the class only answers questions about the JVM. + */ + private JolMeasurement() { + } + + /** + * Stops the calling test unless JOL is in a state in which its byte figures are measurements. + *

+ * Call it as the first statement of every test that takes a number out of JOL. A test that only + * counts objects, or that does not touch JOL at all, must not call it: the object counts of a + * graph walk are correct in every mode, and skipping a census because no agent attached would be + * a skip for no reason. + *

+ * + * @throws org.opentest4j.TestAbortedException if JOL is not sizing through the instrumentation + * agent, or if the mode cannot be determined + */ + static void require() { + final State state = State.CURRENT; + + Assumptions.assumeTrue(state.mode != Mode.UNKNOWN, + () -> "JOL no longer says which of its modes it is sizing objects in. This build reads that " + + "out of the fields " + INSTRUMENTATION_FIELD + " and " + MAGIC_FIELD_OFFSET_FIELD + + " of its HotspotUnsafe, and one of them is gone, so the numbers below could come " + + "from the instrumentation agent or from a layout model and nothing here can tell " + + "them apart. An unlabelled byte figure is not quotable, so none is produced."); + if (!state.magicFieldOffset) { + fail("JOL initialised with " + MAGIC_FIELD_OFFSET + "=false, so a graph walk that reaches a " + + "record class of java.base dies with 'Cannot get the field offset' and no footprint " + + "of this module can be taken. The option is read once, in the class initialiser of " + + "HotspotUnsafe, which runs the first time anything in this JVM touches JOL, so it " + + "cannot be set from a test: falco-benchmarks/build.gradle.kts has to pass " + + "-D" + MAGIC_FIELD_OFFSET + "=true to the test JVM and evidently no longer does."); + } + Assumptions.assumeTrue(state.mode == Mode.INSTRUMENTATION, + () -> "JOL takes its object sizes from " + state.mode.description() + " on this JVM, so " + + "every byte figure below would be a computation presented as a measurement. The " + + "build passes -Djdk.attach.allowAttachSelf=true and -XX:+EnableDynamicAgentLoading " + + "for exactly this reason; a JVM that still refuses the agent cannot answer the " + + "question this test asks, and the answer is left missing rather than guessed."); + } + + /** + * Returns the mode JOL is sizing objects in. + * + * @return the mode of the running JVM + */ + static Mode mode() { + return State.CURRENT.mode; + } + + /** + * Returns the line every JOL table of this module carries in its header. + *

+ * A byte figure without its measurement mode is not quotable, in the same way a footprint without + * its object header mode is not, so the two are printed next to each other everywhere. + *

+ * + * @return the description of how the numbers below it were obtained + */ + static String describe() { + final State state = State.CURRENT; + return String.format(Locale.ROOT, "jol 0.17, sizes from %s, %s=%s, Serviceability Agent %s", + state.mode.description(), MAGIC_FIELD_OFFSET, + state.mode == Mode.UNKNOWN ? "unknown" : Boolean.toString(state.magicFieldOffset), + state.serviceabilityAgent + ? "attached" + : "not attached, so addresses are guesses and no number here is one"); + } + + /** + * Holds what JOL decided, read exactly once. + *

+ * A holder class rather than a lazily filled field, because the read has to happen after + * {@code VM.current()} has initialised JOL and exactly once, which is what class initialisation + * already guarantees. + *

+ */ + private static final class State { + + /** + * What the running JVM told about itself. + */ + static final State CURRENT = read(); + + /** + * Where the byte figures come from. + */ + private final Mode mode; + + /** + * Whether the Serviceability Agent attached, which decides whether addresses are read or + * guessed. Nothing in this module uses an address, so it is reported rather than required. + */ + private final boolean serviceabilityAgent; + + /** + * The value {@link JolMeasurement#MAGIC_FIELD_OFFSET} had when JOL initialised, which is the + * only value that matters and is not necessarily the one the system property carries now. + */ + private final boolean magicFieldOffset; + + /** + * Creates a state. + * + * @param mode where the byte figures come from + * @param serviceabilityAgent whether the Serviceability Agent attached + * @param magicFieldOffset the option value JOL initialised with + */ + private State(Mode mode, boolean serviceabilityAgent, boolean magicFieldOffset) { + this.mode = mode; + this.serviceabilityAgent = serviceabilityAgent; + this.magicFieldOffset = magicFieldOffset; + } + + /** + * Initialises JOL and reads back what it decided. + * + * @return the state of the running JVM + */ + private static State read() { + final VirtualMachine machine = VM.current(); + final Object instrumentation = field(machine.getClass(), INSTRUMENTATION_FIELD, machine); + final Object accurate = field(machine.getClass(), ACCURATE_FIELD, machine); + final Object magic = field(machine.getClass(), MAGIC_FIELD_OFFSET_FIELD, null); + final Mode mode; + + if (instrumentation == Absent.MARKER || magic == Absent.MARKER) { + mode = Mode.UNKNOWN; + } else if (instrumentation == null) { + mode = Mode.LAYOUT_MODEL; + } else { + mode = instrumentation instanceof Instrumentation ? Mode.INSTRUMENTATION : Mode.UNKNOWN; + } + return new State(mode, Boolean.TRUE.equals(accurate), Boolean.TRUE.equals(magic)); + } + + /** + * Reads a field of the JOL virtual machine implementation. + * + * @param type the class to look the field up in + * @param name the name of the field + * @param owner the instance to read from, null for a static field + * @return the value of the field, {@code null} if the field holds null, or + * {@link Absent#MARKER} if the field does not exist or cannot be read + */ + private static Object field(Class type, String name, Object owner) { + try { + final Field field = type.getDeclaredField(name); + field.setAccessible(true); + return field.get(owner); + } catch (ReflectiveOperationException | RuntimeException exception) { + return Absent.MARKER; + } + } + } + + /** + * Distinguishes a field that holds null from a field that is not there at all. + *

+ * The difference is the whole point of the reflective read: {@code instrumentation == null} means + * JOL is modelling sizes, while a missing field means a JOL whose internals moved and about whose + * numbers this build can no longer say anything. Collapsing the two would turn the second case + * into a silent claim about the first. + *

+ */ + private static final class Absent { + + /** + * The value returned for a field that could not be read. + */ + static final Object MARKER = new Object(); + + /** + * Blocks the creation of an instance because the class only holds the marker. + */ + private Absent() { + } + } +} diff --git a/falco-benchmarks/src/test/java/net/onelitefeather/falco/benchmark/instance/PaletteFootprintTest.java b/falco-benchmarks/src/test/java/net/onelitefeather/falco/benchmark/instance/PaletteFootprintTest.java new file mode 100644 index 0000000..b11a871 --- /dev/null +++ b/falco-benchmarks/src/test/java/net/onelitefeather/falco/benchmark/instance/PaletteFootprintTest.java @@ -0,0 +1,757 @@ +package net.onelitefeather.falco.benchmark.instance; + +import it.unimi.dsi.fastutil.ints.Int2IntOpenHashMap; +import it.unimi.dsi.fastutil.ints.IntArrayList; +import it.unimi.dsi.fastutil.ints.IntOpenHashSet; +import net.minestom.server.instance.palette.Palette; +import net.minestom.server.instance.palette.Palettes; +import net.onelitefeather.falco.benchmark.support.BenchmarkConstants; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.parallel.ResourceLock; +import org.junit.jupiter.api.parallel.Resources; +import org.openjdk.jol.info.ClassLayout; +import org.openjdk.jol.info.GraphLayout; + +import java.util.Arrays; +import java.util.Random; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * The {@link PaletteFootprintTest} class measures how many bytes a Minestom block palette retains, + * across every storage model the palette has and across the size of the palette itself. + *

+ * This is a measurement expressed as a test rather than as a JMH benchmark on purpose. The question + * is retained size, not throughput, and retained size is precisely what {@code -prof gc} cannot + * answer: that profiler reports the allocation rate of a benchmark, which says nothing about how + * much a long lived structure holds on to once it has stopped allocating. JOL walks the object graph + * of a live instance instead and returns bytes, which is the unit the entire memory argument of this + * project is denominated in. JOL also needs {@code -Djdk.attach.allowAttachSelf=true} to read the + * real object header layout of the running VM, and the build sets that flag on the test JVM rather + * than on the JMH JVM. That is the second reason this file is a test. + *

+ * + *

Why every table names the mode JOL measured in

+ *

+ * JOL has two ways of answering how large an object is: it asks the instrumentation agent it attached + * to the running JVM, or, when the attach failed, it computes the size from a layout model and keeps + * answering without saying so. Only the first is a measurement, so every header below states which of + * the two produced the numbers under it, and a run that cannot reach the agent stops with an + * assumption rather than publishing a modelled table. {@link JolMeasurement} makes that call and + * explains it; this class only asks it first and prints what it says. + *

+ *

+ * That guard is also what keeps this class from breaking its neighbours. {@code jol.magicFieldOffset}, + * the option {@link ChunkFootprintTest} needs to walk a chunk at all, is read by JOL exactly once, in + * the class initialiser that the first JOL call in the test JVM triggers — which used to be whichever + * of the two classes JUnit happened to run first. It is a JVM argument of the build now, and + * {@link JolMeasurement#require()} verifies that JOL really saw it, from every class that touches JOL, + * so the flag cannot silently go missing again. + *

+ * + *

What the storage models are, and why the null fields are the point

+ *

+ * {@code PaletteImpl} has three storage models and each one drops fields the other two carry. At + * {@code bitsPerEntry == 0} the palette holds a single value in an {@code int} field and every array + * reference is null. In indirect mode, {@code bitsPerEntry} between {@code 4} and {@code 8}, it + * holds a packed {@code long[]} of palette indices, an {@code IntArrayList} that maps an index back + * to a block state, and an {@code Int2IntOpenHashMap} that maps a block state to an index. In direct + * mode, {@code bitsPerEntry == 15}, it holds the packed {@code long[]} alone and both palette + * structures are null again; the field declarations say so in a comment. + *

+ *

+ * A footprint measurement that only printed totals would hide exactly that. The tests below assert + * on the object graph itself: an empty palette must be a single object with nothing hanging off it, a + * direct palette must be exactly two objects, and an indirect palette must hold exactly one of each + * palette structure. If a future Minestom version starts allocating those structures eagerly, these + * assertions fail before any number in a table gets a chance to look plausible. + *

+ * + *

The break-even is the number this file exists for

+ *

+ * The research report claims that the reverse index of the indirect mode makes an indirect palette + * more expensive than a direct one somewhere above {@code 192} entries, and marks the claim as a + * hypothesis, because it came out of arithmetic over assumed object layouts rather than out of a + * measurement. An earlier round of the same arithmetic said {@code 256}. Two hand computations that + * disagree by a factor close to two are not a basis on which to choose a palette representation, so + * the break-even is measured here and nowhere else. + *

+ *

+ * The measurement walks the whole indirect range, one entry at a time, and reports the smallest + * palette size whose indirect footprint reaches the constant footprint of a direct palette. It does + * that twice, because Minestom builds indirect palettes along two different paths and they do not + * cost the same. {@code Palette#load(int[], long[])}, the path the Anvil loader takes, hands the + * palette array to {@code new IntArrayList(int[])} and sizes the reverse map with + * {@code new Int2IntOpenHashMap(int)}, so both structures come out sized to the content. Growing a + * palette through {@code Palette#set(int, int, int, int)}, the path every block placement takes, + * starts from the default capacity and grows in steps, so both structures carry slack. The + * break-even of the two paths is not the same number, and the report only ever spoke of one. + *

+ * + *

Why the alternative reverse index is measured as a bare structure

+ *

+ * {@code Palette} is declared {@code public sealed interface Palette permits PaletteImpl}. A palette + * that swaps the {@code Int2IntOpenHashMap} for a sorted {@code int[]} cannot be written at all: not + * as a subtype, not through reflection and not through a proxy, because the permits clause is + * enforced by the verifier and not by the compiler alone. The alternative is therefore measured as + * what it would be if Falco ever owned its own section storage, namely as bare arrays, and the + * comparison is one of structures rather than of palettes. + *

+ *

+ * Two alternatives are measured, because the substitution is not free of consequences and the two + * ways of paying for it differ by a third of the memory. Keeping the palette in insertion order, as + * Minestom does, means the packed array never has to be rewritten when a state is added, but the + * reverse direction then needs a sorted copy of the states plus a parallel array of the palette + * index each of them maps to: three arrays of the palette size. Keeping the palette in sorted order + * collapses all three into one, because the palette index becomes the position in the sorted array + * and both directions are then the same array, but every insertion in the middle shifts the indices + * of everything behind it and the packed array of {@code 4096} entries has to be remapped. The + * second is the cheaper structure and the more expensive write, and only a measurement of both makes + * that a choice rather than a preference. + *

+ * + *

What this measurement deliberately does not see

+ *

+ * {@code PaletteImpl} keeps a {@code ThreadLocal} write cache of {@code 4096} ints, which is + * {@code 16} KiB per thread that has ever written to a palette and is never released. It hangs off a + * static field, so it is not part of the object graph of any instance and no number below contains + * it. It has to be counted once per thread of the pool, separately. + *

+ * + *

Running it

+ *

+ * The measured numbers depend on the object header layout, so a run has to say which layout it + * means. The build wires both through one property and every table header repeats the mode: + *

+ * 
{@code
+ * ./gradlew :falco-benchmarks:test --tests "*PaletteFootprintTest" -i
+ * ./gradlew :falco-benchmarks:test --tests "*PaletteFootprintTest" -Pfalco.compactHeaders -i
+ * }
+ *

+ * The first line measures the layout of a stock JDK 25 under {@code -XX:-UseCompactObjectHeaders}, + * the second the layout Falco would see under {@code -XX:+UseCompactObjectHeaders}. Both tables are + * needed before a break-even is quoted anywhere, because compact headers take bytes off every one of + * the four objects an indirect palette is made of and none off the payload of the packed + * {@code long[]} of a direct one, which moves the break-even upwards. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ResourceLock(Resources.GLOBAL) +class PaletteFootprintTest { + + /** + * The edge length of a block palette, mirrored from {@code Palette.BLOCK_DIMENSION}. + */ + private static final int DIMENSION = Palette.BLOCK_DIMENSION; + + /** + * The smallest amount of bits an indirect block palette uses per entry. + */ + private static final int MIN_BITS = Palette.BLOCK_PALETTE_MIN_BITS; + + /** + * The largest amount of bits an indirect block palette uses per entry. + * One more bit and the palette switches to direct storage. + */ + private static final int MAX_BITS = Palette.BLOCK_PALETTE_MAX_BITS; + + /** + * The amount of bits a direct block palette uses per entry. + */ + private static final int DIRECT_BITS = Palette.BLOCK_PALETTE_DIRECT_BITS; + + /** + * The amount of entries a block palette holds. + */ + private static final int ENTRIES = DIMENSION * DIMENSION * DIMENSION; + + /** + * The largest palette size that still stays in indirect mode. + * Beyond it both {@code load} and {@code set} switch the palette to direct storage. + */ + private static final int MAX_INDIRECT_SIZE = Palettes.maxPaletteSize(MAX_BITS); + + /** + * The seed every generated block state sequence uses, so two runs measure the same palettes. + *

+ * It is {@link BenchmarkConstants#SEED}, the same seed the JMH benchmarks draw their block state + * sequences from. Sharing it is what lets a footprint printed here be read next to a timing + * printed by {@code PaletteIndirectGetBenchmark} without asking whether the two saw the same + * palettes. + *

+ */ + private static final long SEED = BenchmarkConstants.SEED; + + /** + * The palette sizes the printed tables walk. + *

+ * The ladder is dense around the top of the indirect range because that is where the break-even + * is expected and where the reverse map takes its last rehash step, and sparse below it because + * the shape there is a straight line. + *

+ */ + private static final int[] SIZE_LADDER = {1, 2, 4, 8, 16, 32, 64, 128, 160, 192, 224, 256}; + + /** + * Verifies that a palette which has never been written to is a single object, and reports how + * many bytes that object costs. + *

+ * This is the state the {@code 24} sections of a fresh overworld chunk are in, twice over, once + * for blocks and once for biomes. If the empty palette carried a backing array, the fixed cost of + * a chunk would be dominated by palettes rather than by object headers, and the first row of the + * memory table of the report would point at the wrong thing. + *

+ */ + @Test + void emptyPaletteHoldsNoArrays() { + JolMeasurement.require(); + + Palette palette = Palette.blocks(); + GraphLayout layout = GraphLayout.parseInstance(palette); + + printHeader("empty palette, bitsPerEntry == 0"); + System.out.println(layout.toFootprint()); + + assertEquals(0, palette.bitsPerEntry(), "a fresh block palette must be in single value mode"); + assertEquals(1L, layout.totalCount(), "a single value palette must not reference any object"); + assertEquals(ClassLayout.parseInstance(palette).instanceSize(), layout.totalSize(), + "the retained size of a single value palette must be its own instance size"); + assertFalse(holds(layout, IntArrayList.class), "a single value palette must not hold a forward index"); + assertFalse(holds(layout, Int2IntOpenHashMap.class), "a single value palette must not hold a reverse index"); + } + + /** + * Verifies that a direct palette holds nothing but its packed array, and that its footprint does + * not depend on what is stored in it. + *

+ * The independence is the load bearing half of this test. A direct palette is what every + * generated chunk ends up in, and the reason the break-even below can be a single number rather + * than a curve is that the right hand side of the comparison is constant. Two palettes with + * entirely different content are measured and have to come out equal before that constant is used + * anywhere. + *

+ */ + @Test + void directPaletteHoldsNoPaletteStructures() { + JolMeasurement.require(); + + int[] states = distinctStates(512); + Palette dense = Palette.blocks(DIRECT_BITS); + for (int index = 0; index < ENTRIES; index++) { + dense.set(index & 15, index >> 8, (index >> 4) & 15, states[index % states.length]); + } + Palette sparse = Palette.blocks(DIRECT_BITS); + sparse.set(0, 0, 0, states[1]); + + GraphLayout layout = GraphLayout.parseInstance(dense); + + printHeader("direct palette, bitsPerEntry == " + DIRECT_BITS); + System.out.println(layout.toFootprint()); + + assertEquals(DIRECT_BITS, dense.bitsPerEntry(), "the palette must be in direct mode"); + assertEquals(2L, layout.totalCount(), "a direct palette must be the palette and its packed array"); + assertFalse(holds(layout, IntArrayList.class), "a direct palette must not hold a forward index"); + assertFalse(holds(layout, Int2IntOpenHashMap.class), "a direct palette must not hold a reverse index"); + assertEquals(Palettes.arrayLength(DIMENSION, DIRECT_BITS), packedLength(dense), + "a direct palette must pack every entry at the direct width"); + assertEquals(GraphLayout.parseInstance(sparse).totalSize(), layout.totalSize(), + "the footprint of a direct palette must not depend on its content"); + } + + /** + * Verifies that an indirect palette holds exactly one forward and one reverse index, at every + * width the indirect mode covers. + *

+ * Exactly one of each matters more than it reads. The reverse map is the structure the break-even + * turns on, and a palette that carried a second copy of it, or that shared one with a neighbouring + * palette, would make every byte figure below either double counted or unattributable. + *

+ */ + @Test + void indirectPaletteHoldsBothIndexes() { + JolMeasurement.require(); + + printHeader("indirect palettes, one row per width, filled to the width"); + for (int bits = MIN_BITS; bits <= MAX_BITS; bits++) { + int size = Palettes.maxPaletteSize(bits); + Palette palette = grown(bits, size); + GraphLayout layout = GraphLayout.parseInstance(palette); + + System.out.printf("bitsPerEntry=%2d paletteSize=%3d objects=%d bytes=%d%n", + bits, size, layout.totalCount(), layout.totalSize()); + + assertEquals(bits, palette.bitsPerEntry(), "the palette must stay at the requested width"); + assertEquals(1L, layout.getClassCounts().count(IntArrayList.class), + "an indirect palette must hold exactly one forward index"); + assertEquals(1L, layout.getClassCounts().count(Int2IntOpenHashMap.class), + "an indirect palette must hold exactly one reverse index"); + } + } + + /** + * Reports the footprint grid over every storage model and every palette size that model can hold, + * and verifies the two invariants which make the grid readable. + *

+ * The grid separates the two costs that a single palette footprint mixes together. The packed + * {@code long[]} is a function of the width alone: it is the same amount of bytes at width + * {@code 4} whether the palette holds two states or sixteen. Both index structures are a function + * of the palette size alone. Reading a column downwards therefore prices the width, reading a row + * across prices the size, and only the sum of the two is what a section actually costs. + *

+ *

+ * The width is requested here rather than derived from the size. Minestom would never build a + * palette of width {@code 8} holding two states on its own, but measuring that cell is exactly + * what separates the two costs, and the cell is reachable through {@code Palette#blocks(int)}, + * which takes the width as an argument. + *

+ *

+ * Width {@code 0} and width {@code 15} appear with a single row each, because a single value + * palette holds one value by definition and a direct palette has no palette size at all. Writing + * them as one row rather than repeating a constant across the whole size ladder is what keeps the + * table honest about which cells exist. + *

+ */ + @Test + void footprintGridOverWidthAndSize() { + JolMeasurement.require(); + + printHeader("footprint grid, bytes retained by one block palette"); + System.out.printf("%12s %12s %8s %10s %12s %12s%n", + "bitsPerEntry", "paletteSize", "objects", "bytes", "packedBytes", "indexBytes"); + + row(0, 0, GraphLayout.parseInstance(Palette.blocks())); + row(DIRECT_BITS, 0, GraphLayout.parseInstance(Palette.blocks(DIRECT_BITS))); + + for (int bits = MIN_BITS; bits <= MAX_BITS; bits++) { + long packed = -1L; + long previous = -1L; + for (int size : SIZE_LADDER) { + if (size > Palettes.maxPaletteSize(bits)) { + continue; + } + GraphLayout layout = GraphLayout.parseInstance(grown(bits, size)); + row(bits, size, layout); + + long packedBytes = layout.getClassSizes().count(long[].class); + if (packed < 0) { + packed = packedBytes; + } else { + assertEquals(packed, packedBytes, + "the packed array of width " + bits + " must not depend on the palette size"); + } + assertTrue(layout.totalSize() >= previous, + "a larger palette of width " + bits + " must not retain fewer bytes"); + previous = layout.totalSize(); + } + } + } + + /** + * Measures the break-even between an indirect and a direct palette, once for a palette built by + * {@code load} and once for a palette grown by {@code set}, and reports both. + *

+ * The two curves answer two questions the report asked as one. The {@code load} curve is the + * palette an Anvil region file produces, sized exactly to its content, and it decides whether + * keeping a loaded chunk in indirect mode is worth the memory. The {@code set} curve is the + * palette a running server produces one placement at a time, carrying the slack of two growth + * policies, and it decides whether a chunk that is being edited should be pushed to direct mode + * early rather than be allowed to climb to the top of the indirect range. + *

+ *

+ * The assertions bracket the break-even instead of naming it. A palette holding a single state + * has to be cheaper than a direct one, or the indirect mode would have no reason to exist, and a + * palette filled to the top of the indirect range has to be more expensive than a direct one, or + * there is no break-even inside that range at all and the premise of the report is wrong. Both + * are claims a measurement can settle. The number in between is printed rather than asserted, + * because asserting it would pin down exactly the arithmetic this file was written to replace. + *

+ */ + @Test + void breakEvenBetweenIndirectAndDirect() { + JolMeasurement.require(); + + long direct = GraphLayout.parseInstance(Palette.blocks(DIRECT_BITS)).totalSize(); + + long[] loaded = new long[MAX_INDIRECT_SIZE + 1]; + long[] grown = new long[MAX_INDIRECT_SIZE + 1]; + for (int size = 1; size <= MAX_INDIRECT_SIZE; size++) { + loaded[size] = GraphLayout.parseInstance(loaded(size)).totalSize(); + grown[size] = GraphLayout.parseInstance(grown(naturalBits(size), size)).totalSize(); + } + + printHeader("break-even against a direct palette of " + direct + " bytes"); + System.out.printf("%12s %6s %14s %14s %14s %14s%n", + "paletteSize", "bits", "load() bytes", "set() bytes", "load()-direct", "set()-direct"); + for (int size : SIZE_LADDER) { + System.out.printf("%12d %6d %14d %14d %14d %14d%n", + size, naturalBits(size), loaded[size], grown[size], + loaded[size] - direct, grown[size] - direct); + } + System.out.println("first size at which load() reaches the direct footprint: " + firstAtLeast(loaded, direct)); + System.out.println("first size at which set() reaches the direct footprint: " + firstAtLeast(grown, direct)); + + assertTrue(loaded[1] < direct, + "an indirect palette of one state must be cheaper than a direct one, got " + + loaded[1] + " against " + direct); + assertTrue(loaded[MAX_INDIRECT_SIZE] > direct, + "a full indirect palette must be more expensive than a direct one, got " + + loaded[MAX_INDIRECT_SIZE] + " against " + direct + + "; without that there is no break-even inside the indirect range"); + + int breakEven = firstAtLeast(loaded, direct); + assertTrue(breakEven > 1 && breakEven <= MAX_INDIRECT_SIZE, + "the break-even must lie inside the indirect range, got " + breakEven); + assertTrue(loaded[breakEven - 1] < direct, + "the reported break-even must be the first size that reaches the direct footprint"); + } + + /** + * Measures what the palette would cost if its indexes were plain arrays instead of an + * {@code IntArrayList} plus an {@code Int2IntOpenHashMap}, and reports how far each alternative + * moves the break-even. + *

+ * Three structures are compared at every palette size. The first is what Minestom allocates: the + * list of states in palette order plus the hash map of the reverse direction. The second keeps + * the palette in insertion order and replaces only the reverse direction, which needs a sorted + * copy of the states and a parallel array of palette indices next to the forward array, so three + * arrays in total. The third keeps the palette in sorted order, where the palette index is the + * position in the sorted array and one array serves both directions. + *

+ *

+ * The hash map is the structure with the sharp edges. It is sized through + * {@code new Int2IntOpenHashMap(expected)}, which rounds up to a power of two at load factor + * {@code 0.75} and then still rehashes once the insertions reach that fill, so its footprint is a + * staircase rather than a line, and both of its arrays are one entry longer than the power of + * two. An array pair is exactly four bytes per state per array plus a header. Where the staircase + * steps decides how much of the gap below is real and how much is an artefact of one particular + * palette size, which is why the substituted curves are walked at every size and only printed at + * the ladder. + *

+ * + * @see #breakEvenBetweenIndirectAndDirect() + */ + @Test + void arrayIndexesAgainstFastutilIndexes() { + JolMeasurement.require(); + + long direct = GraphLayout.parseInstance(Palette.blocks(DIRECT_BITS)).totalSize(); + + long[] minestom = new long[MAX_INDIRECT_SIZE + 1]; + long[] withStable = new long[MAX_INDIRECT_SIZE + 1]; + long[] withSorted = new long[MAX_INDIRECT_SIZE + 1]; + + printHeader("index alternatives, bytes retained by the index structures alone"); + System.out.printf("%12s %14s %14s %14s %16s %16s%n", + "paletteSize", "fastutil", "3 arrays", "1 array", "3 arrays-direct", "1 array-direct"); + + for (int size = 1; size <= MAX_INDIRECT_SIZE; size++) { + int[] states = distinctStates(size); + int[] sorted = sortedStates(states); + + long fastutil = GraphLayout.parseInstance(forwardIndex(states), reverseIndex(states)).totalSize(); + long stable = GraphLayout.parseInstance(states.clone(), sorted.clone(), sortedIndices(states)).totalSize(); + long single = GraphLayout.parseInstance(sorted.clone()).totalSize(); + + minestom[size] = GraphLayout.parseInstance(loaded(size)).totalSize(); + withStable[size] = minestom[size] - fastutil + stable; + withSorted[size] = minestom[size] - fastutil + single; + + if (contains(SIZE_LADDER, size)) { + System.out.printf("%12d %14d %14d %14d %16d %16d%n", + size, fastutil, stable, single, + withStable[size] - direct, withSorted[size] - direct); + } + + assertTrue(stable <= fastutil, + "three arrays of " + size + " states must not cost more than a list plus a hash map, got " + + stable + " against " + fastutil); + assertTrue(single <= stable, "one array must not cost more than three of the same length"); + } + + int baseBreakEven = firstAtLeast(minestom, direct); + int stableBreakEven = firstAtLeast(withStable, direct); + int singleBreakEven = firstAtLeast(withSorted, direct); + System.out.println("break-even as Minestom stores it: " + describe(baseBreakEven)); + System.out.println("break-even with a stable sorted index: " + describe(stableBreakEven)); + System.out.println("break-even with a sorted order palette: " + describe(singleBreakEven)); + + assertTrue(stableBreakEven == -1 || stableBreakEven >= baseBreakEven, + "a smaller index must not move the break-even towards the direct mode, got " + + stableBreakEven + " against " + baseBreakEven); + assertTrue(singleBreakEven == -1 || singleBreakEven >= baseBreakEven, + "a smaller index must not move the break-even towards the direct mode, got " + + singleBreakEven + " against " + baseBreakEven); + } + + /** + * Prints one row of the footprint grid. + * + * @param bits the width of the measured palette + * @param size the amount of states the measured palette holds, or {@code 0} when the storage + * model has no palette at all + * @param layout the parsed object graph of the measured palette + */ + private static void row(int bits, int size, GraphLayout layout) { + long packed = layout.getClassSizes().count(long[].class); + long index = layout.getClassSizes().count(IntArrayList.class) + + layout.getClassSizes().count(Int2IntOpenHashMap.class) + + layout.getClassSizes().count(int[].class); + System.out.printf("%12d %12s %8d %10d %12d %12d%n", + bits, size == 0 ? "-" : Integer.toString(size), + layout.totalCount(), layout.totalSize(), packed, index); + } + + /** + * Builds an indirect palette of the requested width and size by writing distinct states into it, + * which is the path a running server takes. + * + * @param bits the width to build at, between {@value #MIN_BITS} and {@value #MAX_BITS} + * @param size the amount of distinct states the palette ends up holding + * @return the built palette + * @throws IllegalArgumentException if the size does not fit into the requested width + * @throws IllegalStateException if the palette left the requested width while being filled + */ + private static Palette grown(int bits, int size) { + if (size < 1 || size > Palettes.maxPaletteSize(bits)) { + throw new IllegalArgumentException("A palette of width " + bits + " cannot hold " + size + " states"); + } + Palette palette = Palette.blocks(bits); + // The constructor already seeded the palette with air at index 0, so the loop starts at the + // second state. The positions are distinct for every index below 256, which is the largest + // palette the indirect mode holds, so no write ever overwrites an earlier one. + int[] states = distinctStates(size); + for (int index = 1; index < size; index++) { + palette.set(index & 15, 0, (index >> 4) & 15, states[index]); + } + if (palette.bitsPerEntry() != bits) { + throw new IllegalStateException("The palette left width " + bits + " for " + palette.bitsPerEntry()); + } + return palette; + } + + /** + * Builds an indirect palette of the requested size through {@code load}, which is the path the + * Anvil loader takes. + *

+ * The packed array is filled with palette indices spread over the whole range rather than left at + * zero. A palette whose packed array points at index {@code 0} everywhere retains the same amount + * of bytes, but it is a palette no chunk on disk could produce, and a fixture that is wrong in a + * way the current measurement happens not to see is a trap for the next one. + *

+ * + * @param size the amount of distinct states the palette holds, from one up to the largest + * palette the indirect mode still holds + * @return the built palette + * @throws IllegalArgumentException if the size would leave the indirect range + * @throws IllegalStateException if {@code load} chose a different width than expected + */ + private static Palette loaded(int size) { + if (size < 1 || size > MAX_INDIRECT_SIZE) { + throw new IllegalArgumentException("A size of " + size + " is outside the indirect range"); + } + int bits = naturalBits(size); + int[] states = distinctStates(size); + long[] packed = new long[Palettes.arrayLength(DIMENSION, bits)]; + Random random = new Random(SEED); + for (int y = 0; y < DIMENSION; y++) { + for (int z = 0; z < DIMENSION; z++) { + for (int x = 0; x < DIMENSION; x++) { + Palettes.write(DIMENSION, bits, packed, x, y, z, random.nextInt(size)); + } + } + } + Palette palette = Palette.blocks(); + palette.load(states, packed); + if (palette.bitsPerEntry() != bits) { + throw new IllegalStateException("load() chose width " + palette.bitsPerEntry() + " instead of " + bits); + } + return palette; + } + + /** + * Returns the width {@code load} picks for a palette of the given size. + *

+ * The formula repeats what {@code PaletteImpl#load(int[], long[])} does, rather than calling + * {@code MathUtils#bitsToRepresent(int)}, so that a fixture never silently follows a change of an + * internal utility that the palette itself no longer uses. + *

+ * + * @param size the amount of states in the palette + * @return the width in bits + */ + private static int naturalBits(int size) { + if (size <= 1) { + return MIN_BITS; + } + return Math.max(MIN_BITS, Integer.SIZE - Integer.numberOfLeadingZeros(size - 1)); + } + + /** + * Returns distinct block state ids, air first, drawn from a fixed seed. + *

+ * Air comes first because every palette a chunk produces holds it at index {@code 0}, and the + * remaining ids are spread over the range a real block registry occupies rather than being + * consecutive. Neither choice changes a byte of the footprint, since both index structures are + * sized by count alone, but a consecutive sequence would be an input no chunk ever has and it + * would flatter any structure that happens to like dense keys. + *

+ * + * @param count the amount of ids to return + * @return the ids, distinct and in a stable order + */ + private static int[] distinctStates(int count) { + int[] states = new int[count]; + IntOpenHashSet seen = new IntOpenHashSet(count); + Random random = new Random(SEED); + seen.add(0); + int written = 1; + while (written < count) { + int candidate = 1 + random.nextInt(26_000); + if (seen.add(candidate)) { + states[written++] = candidate; + } + } + return states; + } + + /** + * Builds the forward index the way {@code load} builds it. + * + * @param states the palette content + * @return the list mapping a palette index to a block state + */ + private static IntArrayList forwardIndex(int[] states) { + return new IntArrayList(states); + } + + /** + * Builds the reverse index the way {@code load} builds it, including its default return value. + * + * @param states the palette content + * @return the map from a block state to its palette index + */ + private static Int2IntOpenHashMap reverseIndex(int[] states) { + Int2IntOpenHashMap map = new Int2IntOpenHashMap(states.length); + map.defaultReturnValue(-1); + for (int index = 0; index < states.length; index++) { + map.put(states[index], index); + } + return map; + } + + /** + * Returns the palette content in ascending order. + * + * @param states the palette content + * @return a sorted copy + */ + private static int[] sortedStates(int[] states) { + int[] sorted = states.clone(); + Arrays.sort(sorted); + return sorted; + } + + /** + * Returns the palette index of each state of {@link #sortedStates(int[])}, at the same position. + * + * @param states the palette content + * @return the parallel index array of the stable sorted alternative + */ + private static int[] sortedIndices(int[] states) { + int[] sorted = sortedStates(states); + int[] indices = new int[states.length]; + for (int index = 0; index < states.length; index++) { + indices[Arrays.binarySearch(sorted, states[index])] = index; + } + return indices; + } + + /** + * Returns the smallest index of the curve whose value reaches the threshold. + * + * @param curve the measured footprints, indexed by palette size, entry {@code 0} unused + * @param threshold the footprint to reach + * @return the palette size, or {@code -1} if the curve never reaches the threshold + */ + private static int firstAtLeast(long[] curve, long threshold) { + for (int size = 1; size < curve.length; size++) { + if (curve[size] >= threshold) { + return size; + } + } + return -1; + } + + /** + * Describes a break-even that may not exist. + * + * @param breakEven the palette size, or {@code -1} + * @return the size, or a sentence saying that the indirect mode never gets that expensive + */ + private static String describe(int breakEven) { + return breakEven == -1 ? "never inside the indirect range" : Integer.toString(breakEven); + } + + /** + * Returns the length of the packed array of a palette. + * + * @param palette the palette to read + * @return the amount of longs the palette packs its entries into, or {@code 0} if it has none + */ + private static int packedLength(Palette palette) { + long[] values = palette.indexedValues(); + return values == null ? 0 : values.length; + } + + /** + * Reports whether the object graph holds an instance of the given class. + * + * @param layout the parsed object graph + * @param type the class to look for + * @return {@code true} if at least one instance is part of the graph + */ + private static boolean holds(GraphLayout layout, Class type) { + return layout.getClassCounts().count(type) > 0; + } + + /** + * Reports whether the array holds the value. + * + * @param values the array to search + * @param value the value to look for + * @return {@code true} if the value is present + */ + private static boolean contains(int[] values, int value) { + for (int candidate : values) { + if (candidate == value) { + return true; + } + } + return false; + } + + /** + * Prints a table header that names the object header layout the numbers below were measured in, + * and the mode JOL measured them with. + *

+ * Without the first a table is unreadable, because {@code -XX:+UseCompactObjectHeaders} changes + * every number in it and the flag is chosen by a Gradle property rather than by this file. + * Without the second it is not even known to be a table of measurements, because JOL falls back + * to a layout model when it cannot attach its agent and reports the model exactly as it reports a + * reading of the heap. + *

+ * + * @param title what the table below measures + */ + private static void printHeader(String title) { + System.out.println(); + System.out.println("== " + title + + " [compactObjectHeaders=" + System.getProperty("falco.compactHeaders", "unknown") + "]"); + System.out.println(" " + JolMeasurement.describe()); + } +} diff --git a/falco-demo/README.md b/falco-demo/README.md index e953aab..aadb56c 100644 --- a/falco-demo/README.md +++ b/falco-demo/README.md @@ -151,16 +151,22 @@ looks at. `FalcoLightingChunk` needs no calls from the outside — `instance.set and every chunk reports its own changes — which is the same one-line setup Minestom asks for with `LightingChunk::new`. The two sides are therefore compared at the same level of effort. -**`FalcoInstance` is deliberately not in it**, and for a hard reason rather than a preference. -`FalcoInstance` accepts only `FalcoChunk`: `Chunk#onLoad` and `Chunk#unload` are package-private in -Minestom, `FalcoChunk` re-exposes them, and an instance in another package has no other way to reach -them — so it refuses anything else with a `FalcoInstanceException` on the first chunk it loads. -`FalcoLightingChunk` extends `DynamicChunk` and is not a `FalcoChunk`, so the two cannot be combined -at all. Given that choice the light wins: what `FalcoInstance` buys — a clean unregister and a block -write guarded per chunk rather than per instance — is invisible to somebody flying through a world -nobody edits, while the light is the first thing they look at. Running both servers on the same -`InstanceContainer` has a second benefit worth as much: the two then differ in the loader and the -chunk type and in nothing else. +**`FalcoInstance` is deliberately not in it, and since US-3.06 that is a choice rather than a +limit.** It used to be neither. `FalcoInstance` accepts only `FalcoChunk` — `Chunk#onLoad` and +`Chunk#unload` are `protected` in Minestom, `FalcoChunk` re-exposes them, and an instance in another +package has no other way to reach them, so it refuses anything else with a `FalcoInstanceException` +on the first chunk it loads. `FalcoLightingChunk` extended `DynamicChunk` back then and was not a +`FalcoChunk`, so the two could not be combined at all and this paragraph had nothing to decide. + +They can now: `FalcoLightingChunk` **is** a `FalcoChunk`, so +`instance.setChunkSupplier(scheduler.supplier())` on a `FalcoInstance` is the whole setup — no +`setChunkLifecycle` pair and no cast. The demo still leaves it out, for a reason that has nothing to +do with whether it works. What `FalcoInstance` buys — a clean unregister and a block write guarded +per chunk rather than per instance — is invisible to somebody flying through a world nobody edits, +while the light is the first thing they look at; and putting it on one side only would make the two +servers differ in three things instead of one, which is exactly what this comparison exists not to +do. The combination itself is pinned by `FalcoStackIntegrationTest` in this module, which is a +stronger statement than a server nobody can quote. --- diff --git a/falco-demo/src/main/java/net/onelitefeather/falco/demo/ServerStack.java b/falco-demo/src/main/java/net/onelitefeather/falco/demo/ServerStack.java index 7d37c1c..24450e0 100644 --- a/falco-demo/src/main/java/net/onelitefeather/falco/demo/ServerStack.java +++ b/falco-demo/src/main/java/net/onelitefeather/falco/demo/ServerStack.java @@ -27,15 +27,16 @@ *

* Both stacks run on an {@code InstanceContainer}, and that is a decision rather than an * oversight. {@link FalcoInstance} is the third published module of this repository and would be - * the obvious third component of the Falco stack. It can now be combined with - * {@link FalcoLightingChunk} — {@code FalcoInstance#setChunkLifecycle} lets a caller who owns both - * types hand over the two {@code protected} hooks, which is what used to make the combination - * impossible — but the demo still does not use it, for a reason that has nothing to do with whether - * it works: this comparison is worth something only while the two servers differ in the loader and - * the chunk type and in nothing else. What {@code FalcoInstance} buys, a clean unregister and a - * block write guarded per chunk instead of per instance, is invisible to somebody flying through a - * world nobody edits, and adding it to one side only would make the two stacks differ in three - * things instead of one. + * the obvious third component of the Falco stack. Nothing stands in the way any more: + * {@link FalcoLightingChunk} is a {@code FalcoChunk} since US-3.06, so + * {@code instance.setChunkSupplier(scheduler.supplier())} on a {@code FalcoInstance} is the whole + * setup — no {@code setChunkLifecycle} pair and no cast, which is what the combination needed while + * the two chunk types still fought over one superclass. The demo still does not use it, for a reason + * that has nothing to do with whether it works: this comparison is worth something only while the two + * servers differ in the loader and the chunk type and in nothing else. What {@code FalcoInstance} + * buys, a clean unregister and a block write guarded per chunk instead of per instance, is invisible + * to somebody flying through a world nobody edits, and adding it to one side only would make the two + * stacks differ in three things instead of one. *

*

* The combination itself is covered by {@code FalcoStackIntegrationTest} in this module, which is @@ -43,7 +44,7 @@ *

* * @author TheMeinerLP - * @version 1.0.0 + * @version 1.1.0 * @since 0.3.0 */ public enum ServerStack { @@ -206,9 +207,10 @@ public String note() { return ""; } - return FalcoInstance.class.getName() + " is deliberately not part of this stack: it can hold a " - + "FalcoLightingChunk now, but adding it to one side only would make the two servers " - + "differ in three things instead of one, and its advantages do not show in a world " - + "nobody edits. See falco-demo/README.md."; + return FalcoInstance.class.getName() + " is deliberately not part of this stack: a " + + "FalcoLightingChunk is a FalcoChunk now and needs nothing but setChunkSupplier to " + + "run in one, but adding it to one side only would make the two servers differ in " + + "three things instead of one, and its advantages do not show in a world nobody " + + "edits. See falco-demo/README.md."; } } diff --git a/falco-demo/src/test/java/net/onelitefeather/falco/demo/FalcoStackIntegrationTest.java b/falco-demo/src/test/java/net/onelitefeather/falco/demo/FalcoStackIntegrationTest.java index 8d70173..0d8568b 100644 --- a/falco-demo/src/test/java/net/onelitefeather/falco/demo/FalcoStackIntegrationTest.java +++ b/falco-demo/src/test/java/net/onelitefeather/falco/demo/FalcoStackIntegrationTest.java @@ -20,28 +20,33 @@ import java.util.UUID; import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; import static org.junit.jupiter.api.Assertions.assertInstanceOf; import static org.junit.jupiter.api.Assertions.assertNotNull; import static org.junit.jupiter.api.Assertions.assertNull; /** - * Proves that the three modules run as one stack. + * Proves that the three modules run as one stack, through both doors that reach it. *

- * This is the combination the project could not build until now, and the reason it could not is - * worth keeping in view: {@code FalcoInstance} accepted only {@code FalcoChunk} because - * {@code Chunk#onLoad()} and {@code Chunk#unload()} are {@code protected} and unreachable across a - * package, while a lighting chunk extends {@code DynamicChunk}. Both demo stacks therefore ran on - * {@code InstanceContainer}, and {@code ServerStack} says so at length. + * This is the combination the project could not build at all, and the reason is worth keeping in + * view: {@code FalcoInstance} accepted only {@code FalcoChunk} because {@code Chunk#onLoad()} and + * {@code Chunk#unload()} are {@code protected} and unreachable across a package, while a lighting + * chunk extended {@code DynamicChunk} — one superclass slot, two claimants. + *

+ *

+ * Two doors, because two of them are open and each is worth pinning. {@code setChunkLifecycle} takes + * a pair of {@code Consumer} and works for a chunk type this repository never sees; that is + * what the first three cases drive, and it is the route a consumer with their own chunk still takes. + * {@code FalcoLightingChunk} no longer needs it, because US-3.06 made it a {@code FalcoChunk}, and + * the last case drives that: a chunk supplier and nothing else. *

*

* The test lives here rather than in one of the three modules because this is the only module that - * may know all of them. The modules stay ignorant of one another: {@code falco-instance} sees a - * {@code Consumer}, {@code falco-light} sees its own class, and the cast that connects them - * is written here, in the code of the caller. + * may know all of them. *

* * @author TheMeinerLP - * @version 1.0.0 + * @version 2.0.0 * @since 0.4.0 */ @ExtendWith(MicrotusExtension.class) @@ -143,4 +148,44 @@ void testTheWholeStackRunsWithTheAnvilLoaderUnderneath(Env env) throws IOExcepti instance.saveChunksToStorage().join(); } } + + /** + * The whole stack with no lifecycle pair at all, which is what US-3.06 bought. + *

+ * Every other case in this class hands {@code FalcoInstance} two {@code Consumer} that + * cast to {@code FalcoLightingChunk}. That pair was the price of the two chunk types being + * unrelated; now one extends the other, so the instance drives the hooks itself and the caller + * writes one line. The unload is asserted as well, because the pair used to be the only thing + * that could clear the loaded flag of this chunk type. + *

+ */ + @Test + void testTheStackNeedsNoLifecyclePairAnyMore(Env env) throws IOException { + ChunkLightService service = new ChunkLightService(); + ChunkLightScheduler scheduler = ChunkLightScheduler.builder(service) + .executor(Runnable::run) + .build(); + + try (FalcoAnvilLoader loader = FalcoAnvilLoader.builder().build(this.worldRoot, OVERWORLD)) { + FalcoInstance instance = + new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD, loader); + instance.setChunkSupplier(scheduler.supplier()); + env.process().instance().registerInstance(instance); + + Chunk chunk = instance.loadChunk(0, 0).join(); + + assertInstanceOf(FalcoLightingChunk.class, chunk); + + place(chunk, 8, 40, 8, Block.GLOWSTONE); + chunk.tick(1L); + + assertEquals(15, service.blockLightAt(chunk, 8, 40, 8), + "the light runs without anybody wiring the two modules together"); + + instance.unloadChunk(chunk); + + assertNull(instance.getChunk(0, 0), "the instance let the chunk go"); + assertFalse(chunk.isLoaded(), "and reached the unload hook without a configured half"); + } + } } diff --git a/falco-demo/src/test/java/net/onelitefeather/falco/demo/ServerStackTest.java b/falco-demo/src/test/java/net/onelitefeather/falco/demo/ServerStackTest.java index 38f8d1a..8e95b3b 100644 --- a/falco-demo/src/test/java/net/onelitefeather/falco/demo/ServerStackTest.java +++ b/falco-demo/src/test/java/net/onelitefeather/falco/demo/ServerStackTest.java @@ -16,7 +16,7 @@ * their class rather than by a label, and that the instance is the same on both sides. * * @author TheMeinerLP - * @version 1.0.0 + * @version 1.1.0 * @since 0.3.0 */ class ServerStackTest { @@ -95,9 +95,14 @@ void testTheFalcoStackExplainsWhyTheFalcoInstanceIsMissing() { String note = ServerStack.FALCO.note(); assertTrue(note.contains("FalcoInstance"), note); - // The reason changed with setChunkLifecycle: the combination is possible now, and what keeps - // the instance out of the demo is that it would make the two servers differ in three things. + // The reason changed twice. It used to be that the combination was impossible; then + // setChunkLifecycle made it reachable through a pair of hooks; since US-3.06 a + // FalcoLightingChunk is a FalcoChunk and needs nothing but a chunk supplier. What keeps the + // instance out of the demo is none of that, it is that it would make the two servers differ + // in three things instead of one. assertTrue(note.contains("FalcoLightingChunk"), note); + assertTrue(note.contains("setChunkSupplier"), note); + assertTrue(note.contains("three things"), note); assertEquals("", ServerStack.MINESTOM.note()); } diff --git a/falco-instance/build.gradle.kts b/falco-instance/build.gradle.kts index 73c5b93..74b6144 100644 --- a/falco-instance/build.gradle.kts +++ b/falco-instance/build.gradle.kts @@ -8,9 +8,11 @@ dependencies { compileOnly(libs.annotations) compileOnly(libs.minestom) compileOnly(libs.fastutil) + compileOnly(libs.flare.fastutil) testImplementation(libs.adventure.nbt) testImplementation(libs.fastutil) + testImplementation(libs.flare.fastutil) testImplementation(libs.annotations) testImplementation(libs.minestom) testImplementation(libs.cyano) diff --git a/falco-instance/src/main/java/net/minestom/server/instance/ChunkViewerCache.java b/falco-instance/src/main/java/net/minestom/server/instance/ChunkViewerCache.java new file mode 100644 index 0000000..8f946ca --- /dev/null +++ b/falco-instance/src/main/java/net/minestom/server/instance/ChunkViewerCache.java @@ -0,0 +1,96 @@ +package net.minestom.server.instance; + +import net.minestom.server.entity.Entity; +import org.jetbrains.annotations.ApiStatus; + +import java.util.List; + +/** + * The {@link ChunkViewerCache} class removes the viewer cache entry a chunk leaves behind, which + * Minestom offers no way to do. + *

+ * The constructor of {@code Chunk} asks the entity tracker of its instance for a {@code Viewable} + * and receives it out of a {@code computeIfAbsent} keyed by the chunk position + * ({@code Chunk.java:74-76}, {@code EntityTrackerImpl.java:207-210}). Nothing removes that entry + * again — not unloading the chunk, not dropping the last reference to it, not unregistering the + * instance — so a world which streams chunks accumulates one entry per position it has ever visited + * and keeps them until the process ends. + *

+ * + *

Why this class lives in a package of Minestom

+ *

+ * {@code EntityTracker#viewable(List, int, int)} is the only public door to that map and it only + * inserts. The map itself ({@code EntityTrackerImpl.TargetEntry#viewers}), its key type + * ({@code EntityTrackerImpl.ChunkViewKey}) and {@code EntityTrackerImpl} are all package-private, so + * a class declared in {@code net.minestom.server.instance} can reach them and nothing else can + * without reflection — which NFR-001 forbids, and which would break on the first JDK that closes the + * door. + *

+ *

+ * The price is a split package: this jar carries a package that {@code minestom.jar} also carries. On + * the classpath that is invisible and package-private access works, because both jars land in the + * same runtime package of the same classloader; on the module path it is fatal, because Minestom is a + * named module and two modules may not own one package. Falco declares no module and neither does + * anything that consumes it, so nothing that works today changes. What this does close is the option + * of Falco becoming a named module while this class stays where it is. + *

+ * + *

What it does not fix

+ *

+ * An {@code InstanceContainer} hands the tracker a fresh {@code unmodifiableList} of its shared + * instances on every chunk construction, and {@code ChunkViewKey#equals} compares that list by + * identity, so no key built here can ever match one of its entries. The unbounded growth of a + * container is not reachable from the outside and is not addressed. What is addressed is the bounded + * entry a {@code FalcoInstance} leaves per position, which is the one this repository is responsible + * for. + *

+ *

+ * A second live chunk at the same position — a copy, for instance — holds its own reference to the + * view and keeps working after the entry is gone; the next chunk constructed there simply receives a + * new one. The view is derived from the tracker on every read, so two of them for one position are + * two caches of the same answer and never two different answers. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ApiStatus.Internal +public final class ChunkViewerCache { + + /** + * Blocks the creation of an instance because this class only reaches into a foreign map. + */ + private ChunkViewerCache() { + } + + /** + * Removes the cached view of a chunk position. + * + * @param instance the instance the chunk belonged to + * @param chunkX the chunk X + * @param chunkZ the chunk Z + * @return true if an entry was removed, false if there was none or the tracker is a foreign + * implementation + */ + public static boolean release(Instance instance, int chunkX, int chunkZ) { + if (!(instance.getEntityTracker() instanceof EntityTrackerImpl tracker)) return false; + final EntityTrackerImpl.TargetEntry entry = + tracker.targetEntries[EntityTracker.Target.PLAYERS.ordinal()]; + + // keySet().remove(...) rather than remove(...), because the value type of that map is a + // private nested class and naming what remove would return is not allowed here. + return entry.viewers.keySet().remove(new EntityTrackerImpl.ChunkViewKey(List.of(), chunkX, chunkZ)); + } + + /** + * Reports how many views the tracker of an instance currently caches. + * + * @param instance the instance to read + * @return the amount of cached views, or {@code -1} if the tracker is a foreign implementation + */ + public static int size(Instance instance) { + if (!(instance.getEntityTracker() instanceof EntityTrackerImpl tracker)) return -1; + return tracker.targetEntries[EntityTracker.Target.PLAYERS.ordinal()].viewers.size(); + } +} diff --git a/falco-instance/src/main/java/net/onelitefeather/falco/instance/BlockStorage.java b/falco-instance/src/main/java/net/onelitefeather/falco/instance/BlockStorage.java new file mode 100644 index 0000000..4bca62b --- /dev/null +++ b/falco-instance/src/main/java/net/onelitefeather/falco/instance/BlockStorage.java @@ -0,0 +1,238 @@ +package net.onelitefeather.falco.instance; + +import net.minestom.server.instance.Section; +import net.minestom.server.instance.block.Block; +import net.minestom.server.registry.RegistryKey; +import net.minestom.server.world.biome.Biome; +import org.jetbrains.annotations.ApiStatus; + +import java.util.List; + +/** + * The {@link BlockStorage} interface is the implementation side of the chunk of Falco. + *

+ * A chunk of Minestom keeps its blocks in a field its subclasses inherit, which means that a chunk + * which wants a different memory layout has to be a different chunk class. That is why + * {@code FalcoChunk} and {@code FalcoLightingChunk} cannot be combined today: both of them extend + * {@code DynamicChunk}, and a class has one superclass. Moving the storage behind this interface + * turns those two branches into two parts that compose. + *

+ *

+ * The split is drawn where the two sides stop needing each other. Everything that is about the + * identity of a chunk stays outside: its position, its lifecycle, its viewers, its heightmaps and + * the packet it sends. Everything that is about where a block physically sits lives here. An + * implementation of this interface therefore never needs an {@code Instance}, and the chunk never + * needs to know whether the blocks below it are sections, a packed array or something off heap. + *

+ *

+ * Coordinates are chunk-local: {@code x} and {@code z} are {@code 0} to {@code 15}, and {@code y} is + * an absolute world height, because that is the form the anvil format uses and because a storage has + * no chunk position to fold a world coordinate against. + *

+ *

+ * That asymmetry is the whole point of the rule and it is the caller's job, not the storage's. + * {@code Chunk#setBlock} is handed instance-level coordinates, so {@code FalcoChunk} masks + * {@code x} and {@code z} once, on its side of the seam, and every implementation here may index by + * them directly — which is what makes a packed layout possible at all, since such a layout has no + * cheap way to detect that it was handed a coordinate belonging to a chunk far away. An + * implementation is free to reject an out-of-range coordinate, and is expected to do so loudly + * rather than to fold it back into range: folding turns a caller error into a block written to the + * wrong place, which no test can distinguish from a block written correctly. + *

+ *

+ * Implementations are not thread-safe on their own. The caller holds the lock of the chunk, which + * {@code Chunk#lockWriteLock()} and {@code Chunk#lockReadLock()} provide. + *

+ * + *

Two ways to reach a section, and why that is not one too many

+ *

+ * {@link #section(int)} and {@link #sections()} answer {@code Chunk#getSection(int)} and + * {@code Chunk#getSections()}, which are public methods of Minestom that hand a {@code Section} to + * an arbitrary caller. A storage cannot know whether such a caller reads or writes, so those two + * have to produce a section the chunk owns. {@link #view(int)} and {@link #views()} are for the + * chunk itself, which does know: its packet builder, its light data builder and its heightmap scan + * only read. Without the second pair a lazy layout would be undone from inside the very class that + * chose it, on the first packet a chunk sends. + *

+ * + * @author TheMeinerLP + * @version 2.0.0 + * @since 0.4.0 + */ +@ApiStatus.Experimental +public interface BlockStorage { + + /** + * Reads the block at a position. + *

+ * A storage always answers with a block and never with {@code null}. A stored value the block + * registry does not know — which a raw palette write or a world from another version can produce + * — is answered with air, because {@code Block.Getter.Condition#NONE} promises a block "no matter + * what" and {@code Block.Getter#getBlock(int, int, int)} dereferences the result. The + * {@code null} case that {@code Chunk#getBlock} has belongs to the chunk, which owns the block + * entity map the condition selects over; nothing here can answer {@code Condition#CACHED}. + *

+ * + * @param x the chunk-local block X, {@code 0} to {@code 15} + * @param y the absolute block Y + * @param z the chunk-local block Z, {@code 0} to {@code 15} + * @param condition what the caller is willing to accept, as {@code Block.Getter} defines it + * @return the block, air if the stored state is unknown, never {@code null} + */ + Block getBlock(int x, int y, int z, Block.Getter.Condition condition); + + /** + * Writes a block to a position. + * + * @param x the chunk-local block X, {@code 0} to {@code 15} + * @param y the absolute block Y + * @param z the chunk-local block Z, {@code 0} to {@code 15} + * @param block the block to write + */ + void setBlock(int x, int y, int z, Block block); + + /** + * Reads the biome at a position. + *

+ * Biomes are stored by their registry id, so a storage that was filled through a raw palette + * write can hold an id no biome answers to. Such a read fails rather than returning + * {@code null}: the caller of a biome getter has no reasonable substitute the way an unknown + * block has air, and a {@code null} would surface far from the write that caused it. + *

+ * + * @param x the chunk-local block X, {@code 0} to {@code 15} + * @param y the absolute block Y + * @param z the chunk-local block Z, {@code 0} to {@code 15} + * @return the biome, never {@code null} + * @throws NullPointerException if the stored id belongs to no registered biome + */ + RegistryKey getBiome(int x, int y, int z); + + /** + * Writes a biome to a position. + *

+ * An unregistered biome is rejected here rather than stored. A biome registry lookup answers a + * miss with {@code -1}, and a palette accepts that value like any other, counts it and hands it + * to the chunk packet — so a storage that did not check would turn a caller error into a corrupt + * chunk that only fails on a read, or on a client, long afterwards. + *

+ * + * @param x the chunk-local block X, {@code 0} to {@code 15} + * @param y the absolute block Y + * @param z the chunk-local block Z, {@code 0} to {@code 15} + * @param biome the biome to write + * @throws IllegalStateException if the biome is not registered + */ + void setBiome(int x, int y, int z, RegistryKey biome); + + /** + * Hands out the sections of this storage, from the bottom one upwards. + *

+ * This is a boundary method. Minestom demands {@code Section} objects for packet serialisation, + * for its light engine and for the anvil writer, so an implementation which does not store them + * has to materialise them here. Calling this is therefore the one operation that can undo + * whatever an implementation saved by not holding them, which is why the chunk calls it only + * where Minestom leaves no choice. + *

+ * + * @return the sections of this storage + */ + List
sections(); + + /** + * Hands out one section of this storage. + * + * @param section the index of the section, counted from the bottom one + * @return the section + */ + Section section(int section); + + /** + * Reports how many sections this storage spans. + * + * @return the amount of sections + */ + int sectionCount(); + + /** + * Hands out one section of this storage as it stands, without creating one. + *

+ * This is the read-only counterpart of {@link #section(int)} and the difference between the two + * is the whole economy of a lazy layout. {@link #section(int)} exists to answer + * {@code Chunk#getSection(int)}, which gives a {@code Section} to a caller this storage knows + * nothing about — a chunk loader, the light engine of Minestom, the generator of an + * {@code InstanceContainer} — and every one of those may write into it, so the slot has to hold a + * section of its own before it is handed over. This method promises the opposite: the caller only + * reads, so an implementation which shares one section between every empty slot may hand that + * shared section out instead of creating a private one. + *

+ *

+ * The contract that comes with it is therefore sharp, and violating it corrupts more than one + * chunk: the returned section must not be written to, neither through its + * palettes nor through its light carriers, and it must not be kept beyond the call. A write + * through a shared section is not a write to this chunk, it is a write to every chunk in the + * process whose slot at that height happens to be empty. + *

+ *

+ * The section a view answers with is always the one the storage currently holds, so a view taken + * before a write shows the write. An implementation must not answer from a snapshot. + *

+ * + * @param section the index of the section, counted from the bottom one + * @return the section as it stands, which may be shared with other chunks + */ + Section view(int section); + + /** + * Hands out the sections of this storage as they stand, without creating any. + *

+ * The same contract as {@link #view(int)}, over the whole chunk: read only, do not keep, and + * expect a shared section wherever the chunk holds nothing. An implementation is expected to + * answer with a list it owns rather than with a fresh one, because this is the method the packet + * builder of a chunk walks, and a list allocated per send is a cost this stage exists to remove + * rather than to add. + *

+ * + * @return the sections as they stand, from the bottom one upwards + */ + List
views(); + + /** + * Reports whether a section is still shared with other chunks rather than owned by this one. + *

+ * The question a caller which is about to write needs answered without triggering the write it is + * asking about. {@code FalcoInstance} uses it to decide whether a generated section is worth + * committing at all, and the tests of this stage use it to prove that a saving happened rather + * than assuming it. + *

+ * + * @param section the index of the section, counted from the bottom one + * @return whether the slot still points at a section this storage does not own + */ + boolean shared(int section); + + /** + * Reports how many sections this storage owns rather than shares. + *

+ * The one number that makes the whole stage assertable. Every claim about a saving is a claim + * about this counter, and every boundary method that materialises raises it, so a test can state + * exactly what a chunk send, a generator run or a save costs instead of estimating it. + *

+ * + * @return the amount of sections this storage holds of its own, between zero and + * {@link #sectionCount()} + */ + int materialisedSections(); + + /** + * Creates a storage holding the same blocks and biomes as this one, sharing nothing with it. + * + * @return the copy + */ + BlockStorage copy(); + + /** + * Resets this storage to the state it had when it was created. + */ + void clear(); +} diff --git a/falco-instance/src/main/java/net/onelitefeather/falco/instance/BlockWriter.java b/falco-instance/src/main/java/net/onelitefeather/falco/instance/BlockWriter.java new file mode 100644 index 0000000..6610c78 --- /dev/null +++ b/falco-instance/src/main/java/net/onelitefeather/falco/instance/BlockWriter.java @@ -0,0 +1,400 @@ +package net.onelitefeather.falco.instance; + +import net.kyori.adventure.nbt.CompoundBinaryTag; +import net.minestom.server.MinecraftServer; +import net.minestom.server.coordinate.BlockVec; +import net.minestom.server.coordinate.CoordConversion; +import net.minestom.server.coordinate.Point; +import net.minestom.server.coordinate.Vec; +import net.minestom.server.entity.Player; +import net.minestom.server.event.EventDispatcher; +import net.minestom.server.event.instance.InstanceBlockUpdateEvent; +import net.minestom.server.event.player.PlayerBlockBreakEvent; +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.block.Block; +import net.minestom.server.instance.block.Block.Getter.Condition; +import net.minestom.server.instance.block.BlockEntityType; +import net.minestom.server.instance.block.BlockFace; +import net.minestom.server.instance.block.BlockHandler; +import net.minestom.server.instance.block.rule.BlockPlacementRule; +import net.minestom.server.network.packet.server.play.BlockChangePacket; +import net.minestom.server.network.packet.server.play.BlockEntityDataPacket; +import net.minestom.server.network.packet.server.play.WorldEventPacket; +import net.minestom.server.utils.PacketSendingUtils; +import net.minestom.server.utils.block.BlockUtils; +import net.minestom.server.utils.chunk.ChunkCache; +import net.minestom.server.world.DimensionType; +import net.minestom.server.worldevent.WorldEvent; +import org.jetbrains.annotations.ApiStatus; +import org.jetbrains.annotations.Contract; +import org.jetbrains.annotations.Nullable; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +import java.util.Map; +import java.util.Objects; +import java.util.concurrent.ConcurrentHashMap; + +/** + * The {@link BlockWriter} class is everything a {@link FalcoInstance} does when a block changes: the + * three entry points, the write itself, the neighbours it wakes, the packets it sends and the event + * it announces. + * + *

What is held while what runs

+ *

+ * No lock of the instance is taken at all; the only lock in a write is the write lock of the one + * chunk that receives the block. The container of Minestom instead takes its own monitor around the + * whole of this, which turns every block write in the world into a queue behind every other one, and + * two writes to two chunks have no reason to wait for each other. That is NFR-006, and it is a + * property of the ordering of this class rather than of any one statement in it. + *

+ *

+ * The chunk lock is taken before the placement rule is asked and given back after the block reached + * the storage. Four pieces of foreign code therefore run under it, and it is worth naming + * them rather than pretending otherwise: {@code BlockPlacementRule#blockPlace} of the placed block, + * and — inside {@link FalcoChunk#setBlock(int, int, int, Block, BlockHandler.Placement, + * BlockHandler.Destroy)}, which requires that very lock — {@code BlockHandler#onDestroy} of the block + * that was replaced, {@code BlockHandler#onPlace} of the one that replaced it, and + * {@link ChunkLifecycleListener#onBlockChange} of whatever listens to that chunk. The first three are + * inside because they are part of deciding and recording what the block is: a rule that runs + * after the write would be answering about a block already written, and a handler that runs after the + * lock was given back could be told about a block a second writer has since overwritten. + *

+ *

+ * The fourth is the one a reader of this class is least likely to find, and it is the reason this + * paragraph counts four rather than three. A block handler and a placement rule are attached to a + * block, so somebody put them where the write would meet them; a lifecycle listener is registered + * once, on {@link ChunkLifecycle} or on a single chunk, and then runs on every block that chunk ever + * receives without anybody touching a block to arrange it. It sits at the end of + * {@link FalcoChunk#setBlock(int, int, int, Block, BlockHandler.Placement, BlockHandler.Destroy)}, + * after the heightmaps, so that it sees a finished chunk — and therefore inside the lock this method + * is still holding. {@link ChunkLifecycleListener#onBlockChange} states the same thing from the other + * side; {@code BlockWriterTest} measures it from inside the callback, the way it measures the other + * three. + *

+ *

+ * Three further steps run outside it, and this is where the ordering is deliberate: the + * neighbour pass, the two packets and {@code InstanceBlockUpdateEvent} all happen after the lock was + * given back. Each of them reaches code this module does not own as well — a rule reshaping a + * neighbour, a viewer, an arbitrary listener — but none of them is needed to establish the block, so + * none of them has a reason to hold a chunk lock while it runs. The neighbour pass is the sharpest + * case: a neighbour usually lives in another chunk and takes that chunk's lock on the way, so running + * it inside would mean holding two chunk locks at once, in an order two concurrent writes can + * disagree about. + *

+ * + *

The hazard that the handlers leave standing

+ *

+ * What is inside the lock is not free of that same problem, and no amount of ordering in this class + * removes it: a {@code BlockHandler#onPlace} or {@code #onDestroy} that writes a block in + * another chunk re-enters {@link #write} and takes a second chunk write lock while the first + * one is still held. Two such writes started in opposite chunk order on two threads deadlock each + * other. This is a real hazard of this design and not a theoretical one; it is simply the price of not + * having an instance-wide monitor, which is exactly what {@code InstanceContainer} pays for by + * serialising every block write in the world. It is inherited behaviour, unchanged from before this + * class existed, and it is written here so that the next person to touch the lock finds it stated + * rather than has to derive it. + *

+ *

+ * It applies to {@link ChunkLifecycleListener#onBlockChange} word for word, and there it is not + * inherited from anywhere: a listener which answers a block change by writing a block in a + * neighbouring chunk — the shape a light engine or a redstone-like rule reaches for first — is the + * same nested lock as a handler doing it, on the hottest path of this module, installed once and + * running for every block of every chunk it was given to. + *

+ *

+ * The class exists so that ordering is a thing somebody can look at. It used to be the tail of one + * {@code private} method of a class of more than 1 300 lines, where moving a single + * {@code unlockWriteLock()} one line down would have undone the measurement of stage 1 without + * failing anything. + *

+ * + *

Why the write takes a {@link FalcoChunk}

+ *

+ * Because the block setter carrying a placement and a destruction is {@code protected} on + * {@code Chunk} and only widened to public by {@code DynamicChunk}. That is a lifecycle barrier of the + * same kind as the two hooks {@link FalcoChunk} re-exposes, and it is answered the same way; + * {@link FalcoChunk#require(Chunk)} is where the check lives, shared with {@link FalcoInstance}. + *

+ *

+ * This type is experimental. The instance module is new and its API may still change. + *

+ * + * @author TheMeinerLP + * @version 1.2.0 + * @since 0.4.0 + */ +@ApiStatus.Experimental +public final class BlockWriter { + + private static final Logger LOGGER = LoggerFactory.getLogger(BlockWriter.class); + + /** + * The faces a block change offers to its neighbours for a placement rule update. + */ + private static final BlockFace[] BLOCK_UPDATE_FACES = { + BlockFace.WEST, BlockFace.EAST, BlockFace.NORTH, BlockFace.SOUTH, BlockFace.BOTTOM, BlockFace.TOP + }; + + /** + * The instance the written blocks belong to. + *

+ * Reached for the chunk map, the dimension and the events. Everything else this class needs it + * carries itself. + *

+ */ + private final FalcoInstance owner; + + /** + * The blocks changed since the last end of tick, used to break recursion between block handlers. + *

+ * Concurrent rather than a plain map behind a lock that guarded nothing, which is the shape the + * container has. + *

+ */ + private final Map currentlyChangingBlocks = new ConcurrentHashMap<>(); + + /** + * When the last block of the instance changed, in nanoseconds of an arbitrary origin. + *

+ * Volatile because a block write and a reader of the timestamp are rarely the same thread, and a + * stale read here is a batch which believes nothing has changed. + *

+ */ + private volatile long lastBlockChangeTime = System.nanoTime(); + + /** + * Creates a block writer for an instance. + * + * @param owner the instance the written blocks belong to + */ + public BlockWriter(FalcoInstance owner) { + this.owner = Objects.requireNonNull(owner, "the owner of a block writer cannot be null"); + } + + /** + * Writes a block, loading its chunk first if that is allowed. + * + * @param x the block X + * @param y the block Y + * @param z the block Z + * @param block the block to write + * @param doBlockUpdates true to let the neighbours of the block reshape themselves + * @throws IllegalStateException if the chunk is not loaded and auto chunk load is off + */ + public void setBlock(int x, int y, int z, Block block, boolean doBlockUpdates) { + Chunk chunk = this.owner.getChunkAt(x, z); + if (chunk == null) { + if (!this.owner.lifecycle().autoLoad()) { + throw new IllegalStateException( + "tried to set a block in the unloaded chunk " + CoordConversion.globalToChunk(x) + + ":" + CoordConversion.globalToChunk(z) + " while auto chunk load is disabled"); + } + chunk = this.owner.loadChunk(CoordConversion.globalToChunk(x), CoordConversion.globalToChunk(z)).join(); + } + if (chunk.isLoaded()) write(FalcoChunk.require(chunk), x, y, z, block, null, null, doBlockUpdates, 0); + } + + /** + * Carries out a placement. + * + * @param placement the placement to carry out + * @param doBlockUpdates true to let the neighbours of the placed block reshape themselves + * @return true if the placement reached a chunk, false if there is no loaded chunk at its position + */ + public boolean placeBlock(BlockHandler.Placement placement, boolean doBlockUpdates) { + final Point blockPosition = placement.getBlockPosition(); + final Chunk chunk = this.owner.getChunkAt(blockPosition); + if (chunk == null || !chunk.isLoaded()) return false; + write(FalcoChunk.require(chunk), blockPosition.blockX(), blockPosition.blockY(), blockPosition.blockZ(), + placement.getBlock(), placement, null, doBlockUpdates, 0); + return true; + } + + /** + * Lets a player break a block. + * + * @param player the player who broke the block + * @param blockPosition the position of the broken block + * @param blockFace the face the player broke the block from + * @param doBlockUpdates true to let the neighbours of the broken block reshape themselves + * @return true if a block was broken, false if there is nothing to break or the event was cancelled + */ + public boolean breakBlock(Player player, Point blockPosition, BlockFace blockFace, boolean doBlockUpdates) { + final Chunk chunk = this.owner.getChunkAt(blockPosition); + if (chunk == null || !chunk.isLoaded() || chunk.isReadOnly()) return false; + + final Block block = this.owner.getBlock(blockPosition); + if (block.isAir()) { + // The client believes there is a block here; hand it the chunk it actually has. + chunk.sendChunk(player); + return false; + } + final PlayerBlockBreakEvent event = new PlayerBlockBreakEvent(player, this.owner, block, Block.AIR, + blockPosition.asBlockVec(), blockFace); + EventDispatcher.call(event); + if (event.isCancelled()) return false; + + final Block resultBlock = event.getResultBlock(); + write(FalcoChunk.require(chunk), blockPosition.blockX(), blockPosition.blockY(), blockPosition.blockZ(), resultBlock, + null, new BlockHandler.PlayerDestroy(block, resultBlock, this.owner, blockPosition, player), + doBlockUpdates, 0); + PacketSendingUtils.sendGroupedPacket(chunk.getViewers(), + new WorldEventPacket(WorldEvent.PARTICLES_DESTROY_BLOCK.id(), blockPosition, block.stateId(), false), + // The breaking player already played the effect locally. + viewer -> !viewer.equals(player)); + return true; + } + + /** + * Writes a block into a chunk and tells everyone who needs to know. + *

+ * The write lock of the given chunk is the only lock taken, and it is held from the placement rule + * to the end of {@link FalcoChunk#setBlock(int, int, int, Block, BlockHandler.Placement, + * BlockHandler.Destroy)} — which means across the rule, across the block handlers of the old and + * the new block, and across the lifecycle listener of the chunk. The neighbour pass, the packets + * and the event follow it with no lock held. What that buys, and the re-entrancy hazard the four + * of them leave standing, is the subject of the class documentation. + *

+ *

+ * The chunk is taken rather than looked up, which is what makes this reachable one write at a + * time: the caller decides which chunk receives the block, so a write can be driven against a + * chunk that no instance ever published. + *

+ * + * @param chunk the chunk which receives the block, has to be loaded + * @param x the block X + * @param y the block Y + * @param z the block Z + * @param block the block to write + * @param placement the placement which caused the write, null if it was not a placement + * @param destroy the destruction which caused the write, null if it was not a break + * @param doBlockUpdates true to let the neighbours of the block reshape themselves + * @param updateDistance how many neighbour updates deep this write already is + */ + public void write(FalcoChunk chunk, int x, int y, int z, Block block, + @Nullable BlockHandler.Placement placement, @Nullable BlockHandler.Destroy destroy, + boolean doBlockUpdates, int updateDistance) { + if (chunk.isReadOnly()) return; + final DimensionType dimension = this.owner.getCachedDimensionType(); + if (y >= dimension.maxY() || y < dimension.minY()) { + LOGGER.warn("tried to set a block outside the world bounds, should be within [{}, {}): {}", + dimension.minY(), dimension.maxY(), y); + return; + } + final BlockVec blockPosition = new BlockVec(x, y, z); + // A handler which destroys its own block would otherwise recurse until the stack ends. + if (Objects.equals(this.currentlyChangingBlocks.get(blockPosition), block)) return; + this.currentlyChangingBlocks.put(blockPosition, block); + + Block placed = block; + chunk.lockWriteLock(); + try { + this.lastBlockChangeTime = System.nanoTime(); + final BlockPlacementRule rule = MinecraftServer.getBlockManager().getBlockPlacementRule(placed); + if (placement != null && rule != null && doBlockUpdates) { + placed = Objects.requireNonNullElse(rule.blockPlace(placementState(placement, placed, blockPosition)), Block.AIR); + } + chunk.setBlock(x, y, z, placed, placement, destroy); + } finally { + chunk.unlockWriteLock(); + } + + // Outside the chunk lock on purpose: a neighbour may live in another chunk, and taking a + // second chunk lock while holding the first is how two block writes deadlock each other. + if (doBlockUpdates) updateNeighbours(blockPosition, updateDistance); + + chunk.sendPacketToViewers(new BlockChangePacket(blockPosition, placed.stateId())); + final BlockEntityType blockEntityType = placed.registry().blockEntityType(); + if (blockEntityType != null) { + final CompoundBinaryTag data = BlockUtils.extractClientNbt(placed); + chunk.sendPacketToViewers(new BlockEntityDataPacket(blockPosition, blockEntityType, data)); + } + EventDispatcher.call(new InstanceBlockUpdateEvent(this.owner, blockPosition, placed)); + } + + /** + * Builds the state a placement rule is asked about. + * + * @param placement the placement which caused the write + * @param block the block which is about to be placed + * @param blockPosition the position the block goes to + * @return the state to hand to {@code BlockPlacementRule#blockPlace} + */ + @Contract("_, _, _ -> new") + private BlockPlacementRule.PlacementState placementState(BlockHandler.Placement placement, Block block, + Point blockPosition) { + if (placement instanceof BlockHandler.PlayerPlacement playerPlacement) { + final Player player = playerPlacement.getPlayer(); + return new BlockPlacementRule.PlacementState(this.owner, block, playerPlacement.getBlockFace(), blockPosition, + new Vec(playerPlacement.getCursorX(), playerPlacement.getCursorY(), playerPlacement.getCursorZ()), + player.getPosition(), player.getItemInHand(playerPlacement.getHand()), player.isSneaking()); + } + return new BlockPlacementRule.PlacementState(this.owner, block, null, blockPosition, null, null, null, false); + } + + /** + * Lets the six neighbours of a changed block reshape themselves. + * + * @param blockPosition the position of the block which changed + * @param updateDistance how many neighbour updates deep the causing write already was + */ + private void updateNeighbours(Point blockPosition, int updateDistance) { + final ChunkCache cache = new ChunkCache(this.owner, null, null); + final DimensionType dimension = this.owner.getCachedDimensionType(); + for (BlockFace face : BLOCK_UPDATE_FACES) { + final var direction = face.toDirection(); + final int neighbourX = blockPosition.blockX() + direction.normalX(); + final int neighbourY = blockPosition.blockY() + direction.normalY(); + final int neighbourZ = blockPosition.blockZ() + direction.normalZ(); + if (neighbourY < dimension.minY() || neighbourY >= dimension.maxY()) continue; + final Block neighbour = cache.getBlock(neighbourX, neighbourY, neighbourZ, Condition.NONE); + if (neighbour == null || neighbour.isAir()) continue; + final BlockPlacementRule rule = MinecraftServer.getBlockManager().getBlockPlacementRule(neighbour); + if (rule == null || updateDistance >= rule.maxUpdateDistance()) continue; + + final Vec neighbourPosition = new Vec(neighbourX, neighbourY, neighbourZ); + final Block updated = rule.blockUpdate(new BlockPlacementRule.UpdateState( + this.owner, neighbourPosition, neighbour, face.getOppositeFace())); + if (neighbour.equals(updated)) continue; + final Chunk neighbourChunk = this.owner.getChunkAt(neighbourPosition); + if (neighbourChunk == null || !neighbourChunk.isLoaded()) continue; + write(FalcoChunk.require(neighbourChunk), neighbourX, neighbourY, neighbourZ, updated, null, null, + true, updateDistance + 1); + } + } + + /** + * Gets the time at which the last block of the instance changed. + *

+ * Only usable as a delta against another reading of the same clock. + *

+ * + * @return the time of the last block change in nanoseconds + */ + public long lastChangeTime() { + return this.lastBlockChangeTime; + } + + /** + * Records that a block of the instance changed. + *

+ * Needed when blocks are written through a {@link Chunk} directly, which bypasses this writer. + *

+ */ + public void refreshLastChangeTime() { + this.lastBlockChangeTime = System.nanoTime(); + } + + /** + * Clears the recursion guard of the block writes. + *

+ * The guard is scoped to a single tick, which is what makes it a guard rather than a memory: a + * handler which writes its own block again is stopped within the tick it started in, and the same + * block can be written to the same position again in the next one. + *

+ */ + public void endTick() { + this.currentlyChangingBlocks.clear(); + } +} diff --git a/falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkGeneration.java b/falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkGeneration.java new file mode 100644 index 0000000..51af9b4 --- /dev/null +++ b/falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkGeneration.java @@ -0,0 +1,450 @@ +package net.onelitefeather.falco.instance; + +import it.unimi.dsi.fastutil.ints.Int2ObjectMap; +import net.minestom.server.coordinate.CoordConversion; +import net.minestom.server.coordinate.Point; +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.Section; +import net.minestom.server.instance.block.Block; +import net.minestom.server.instance.generator.GenerationUnit; +import net.minestom.server.instance.generator.Generator; +import net.minestom.server.instance.generator.GeneratorImpl; +import net.minestom.server.instance.palette.Palette; +import net.minestom.server.registry.Registries; +import org.jetbrains.annotations.ApiStatus; +import org.jetbrains.annotations.Nullable; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; +import java.util.Map; +import java.util.concurrent.ConcurrentHashMap; +import java.util.function.Function; + +/** + * The {@link ChunkGeneration} class runs a generator over a chunk and commits what it produced. + *

+ * It is a collaborator of {@code ChunkLifecycle} rather than a part of the facade, and the reason is + * that a chunk is generated exactly once and that once is inside its load. Splitting generation off + * as a fifth part of the facade would give the instance a field nothing but the lifecycle ever + * touches. + *

+ *

+ * It reaches a chunk which is not the one it was asked about through the function it was built with + * rather than through an instance. A fork writes into a neighbour, and a neighbour is the only thing + * this class ever needs a world for; taking that as a parameter is what lets it be driven by a test + * that has no instance at all. + *

+ *

+ * This type is experimental. The instance module is new and its API may still change. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ApiStatus.Experimental +public final class ChunkGeneration { + + /** + * The registries the biomes of a generated chunk are looked up in. + */ + private final Registries registries; + + /** + * How a chunk at a point is found, for the forks which land outside the generated chunk. + */ + private final Function chunkAt; + + /** + * The section modifiers a generator produced for chunks which were not loaded at the time, keyed + * by the chunk index of the chunk they belong to. + *

+ * A generator may write outside the chunk it was asked about through + * {@link GenerationUnit#fork(java.util.function.Consumer)}. Those writes cannot be applied yet + * when their target does not exist, and dropping them would make a generator produce different + * worlds depending on the order in which chunks happened to be requested. + *

+ */ + private final Map> generationForks = new ConcurrentHashMap<>(); + + /** + * The generator which fills a chunk no loader knows about, null while the world stays empty. + */ + private volatile @Nullable Generator generator; + + /** + * Creates a generation side. + * + * @param registries the registries the biomes of a generated chunk are looked up in + * @param chunkAt how a chunk at a point is found, for forks which land outside + */ + public ChunkGeneration(Registries registries, Function chunkAt) { + this.registries = registries; + this.chunkAt = chunkAt; + } + + /** + * Returns the generator which fills a chunk no loader knows about. + * + * @return the current generator, null if chunks without a loader stay empty + */ + public @Nullable Generator generator() { + return this.generator; + } + + /** + * Changes the generator which fills a chunk no loader knows about. + *

+ * Chunks which are already loaded are not affected. A generator is asked for a chunk exactly + * once, when that chunk is created, so changing it later changes the parts of the world which are + * not there yet. + *

+ * + * @param generator the new generator, null to let chunks without a loader stay empty + */ + public void generator(@Nullable Generator generator) { + this.generator = generator; + } + + /** + * Returns how many chunk positions are waiting for a fork to be delivered to them. + *

+ * Exposed because a map nothing can observe is a map nothing can assert, and a fork for a chunk + * that is never requested is the one case that leaks quietly. + *

+ * + * @return the amount of positions with a pending fork + */ + public int pendingForks() { + return this.generationForks.size(); + } + + /** + * Drops every fork which is still waiting for its chunk. + *

+ * A fork whose target chunk was never requested waits forever, and after a shutdown there is + * nothing left it could wait for. + *

+ */ + public void clearPending() { + this.generationForks.clear(); + } + + /** + * Runs a generator over a chunk and commits everything it produced in one step. + *

+ * The generator writes into copies of the palettes of the chunk, not into the palettes + * themselves, and the copies are moved over only after the generator returned. That is the whole + * difference to {@code InstanceContainer#generateChunk(Chunk, Generator)}, which hands the live + * palettes over and catches whatever the generator throws into the exception manager of the + * server. A generator which fails halfway there leaves a chunk that is half built, published and + * reported as loaded, and the caller who asked for the chunk is told nothing. Here the failure + * travels to that caller and the chunk is exactly as it was. + *

+ *

+ * The copies cost one palette clone per section. On a chunk which is still empty — the case + * which matters, because that is where a generator normally runs — a palette is in its single + * value mode and holds no array at all, so the clone is a few bytes. + *

+ *

+ * Those copies are taken from the views of the storage and not from its sections. That is + * the difference between a lazy chunk which survives its own generator and one which does not: + * {@code Chunk#getSections()} materialises every section it hands out, so staging a generation + * through it would create all twenty-four sections of a chunk before the generator has written a + * single block, and the section a generator decides not to fill would already exist by the time + * that decision is made. {@link BlockStorage#view(int)} promises the opposite and is read-only, + * which is all the staging needs: the palettes handed to the generator are clones either way. + *

+ *

+ * The write lock of the chunk is held for the commit only. Minestom holds it across the whole + * generator instead, which stops every read and every write of that chunk for as long as the + * generator runs. + *

+ * + *

Why the commit is two passes and not one

+ *

+ * Every palette is moved over first, and only then are the blocks written that need more than a + * palette entry. The two used to be one pass and that was a defect, because the second half is + * not a write into a section: {@link #writeSpecialBlocks} goes through {@code Chunk#setBlock}, + * which begins with {@code if (needsCompleteHeightmapRefresh) calculateFullHeightmap()}. On a + * chunk that was just generated the flag is true, so the first such block computes both + * heightmaps — over whatever part of the chunk had been committed by then. Everything above the + * section that block happens to sit in is still empty at that moment and the heights come out + * short. + *

+ *

+ * What made it permanent rather than merely early is that nothing can re-arm it. + * {@code Heightmap#refresh(int)} sets a {@code private needsRefresh} to false, and the + * {@code chunk.invalidate()} below only flips the flag of the chunk; the next + * {@code calculateFullHeightmap} calls {@code refresh(startY)} again and that method returns on + * its first line. The wrong heights then go into every chunk packet for the life of the chunk. + * {@code FalcoInstanceGeneratorTest#testTheHeightmapsSeeTheWholeChunkAndNotHalfOfIt} pins the + * case with the numbers it produced: {@code 79} instead of {@code 127}. + *

+ *

+ * The {@code chunk.invalidate()} sits between the two passes rather than after them, so that the + * refresh the first special block triggers is one over the complete chunk and not one over + * heights the palettes have meanwhile invalidated. Minestom arrives at the same order by a + * different route: {@code InstanceContainer} commits every palette in one loop and runs + * {@code applyGenerationData} afterwards. + *

+ * + * @param chunk the chunk to fill + * @param generator the generator to run over the chunk + */ + public void apply(Chunk chunk, Generator generator) { + final BlockStorage storage = storageOf(chunk); + final int sectionCount = storage.sectionCount(); + final GeneratorImpl.GenSection[] staged = new GeneratorImpl.GenSection[sectionCount]; + Arrays.setAll(staged, index -> { + final Section view = storage.view(index); + return new GeneratorImpl.GenSection(view.blockPalette().clone(), view.biomePalette().clone()); + }); + final GeneratorImpl.UnitImpl unit = GeneratorImpl.chunk(this.registries.biome(), staged, + chunk.getChunkX(), chunk.getMinSection(), chunk.getChunkZ()); + + generator.generate(unit); + + chunk.lockWriteLock(); + try { + for (int index = 0; index < sectionCount; index++) { + commitSection(storage, index, staged[index]); + } + chunk.invalidate(); + for (int index = 0; index < sectionCount; index++) { + writeSpecialBlocks(chunk, staged[index].specials(), + (chunk.getMinSection() + index) * Chunk.CHUNK_SECTION_SIZE); + } + } finally { + chunk.unlockWriteLock(); + } + + applyForks(chunk, unit); + applyPending(chunk); + } + + /** + * Writes one generated section back into the chunk, or leaves the chunk alone if it produced + * nothing. + *

+ * The skip is what makes a lazy layout survive its own generator. A generator normally fills the + * lower third of a chunk and leaves everything above the terrain untouched — the census of a real + * overworld puts that untouched share at {@code 62,24 %} of the sections of a finished chunk — and + * committing an empty palette into an empty section would create twenty-four sections to write + * nothing into twenty of them. The condition is the one {@code InstanceContainer} already applies + * to fork sections at {@code InstanceContainer.java:434}, extended by the biomes and by the special + * blocks, since either of those can be the only thing a generator produced for a section. + *

+ *

+ * That {@code 62,24 %} is a census of block content, and the saving is worth that much + * only for a generator which leaves the sections above its terrain alone entirely. A biome is + * stored per section whether the section holds a block or not, so a generator which calls + * {@code UnitModifier#fillBiome} on the chunk unit — the ordinary way to give a chunk a biome — + * reaches every one of the twenty-four section modifiers, fills every biome palette, and this + * method then materialises all twenty-four sections. Nothing is lost there and nothing is wrong: + * a section which has to carry a biome has to exist. It is written down because the number on its + * own reads like a promise about every generator, and it is a promise about generators which write + * blocks. {@code SectionMaterialisationTest} holds both cases side by side, at {@code 4} and at + * {@code 24}. + *

+ *

+ * Each of the three clauses is the last line of defence for one kind of content, and each is + * covered by a case which fails if that clause is dropped. The blocks are the ordinary case; a + * section whose only content is a biome is the second; a section whose only content is a handler on + * air is the third, and it is the subtle one, because {@code SectionModifierImpl#handleCache} + * writes such a block into the palette as its state id, which for air is {@code 0} — the palette + * reports {@code count() == 0} and the specials map is the only evidence the generator was there. + *

+ *

+ * The specials clause stays in the condition even though this method no longer writes them — + * {@link #apply} does, in a second pass, for the reason stated there. It has to: the + * block of that third case is air with a handler, and {@link BlockStorage#setBlock} skips a write + * of air into a shared slot, so the section would stay shared and the storage would answer a + * question about it without ever having one. Materialising it here is what keeps that section a + * section. + *

+ *

+ * A section that is still shared and received nothing needs no write at all, and that is exactly + * what the condition tests. A section the chunk already owns is committed unconditionally: it + * holds content from a loader or an earlier write, and an empty generated palette is a statement + * about what the generator produced and not about what the chunk should end up holding. + *

+ *

+ * The compaction afterwards is US-2.03. A generator writes through {@code GenSection} palettes + * which grow to fifteen bits per entry and never shrink again, because nothing in the main source + * tree of Minestom ever calls {@code Palette#optimize} — a generated chunk retains + * {@code 203 840} bytes where the same content packed to its minimum width retains {@code 84 800}. + * What that costs in time is measured by {@code GeneratorCommitBenchmark} and it is not assumed to + * be free: {@code 576,7 µs} against {@code 22,0 µs} for the bare commit of a chunk of twenty-four + * sections. It goes through {@link PaletteCompaction} rather than straight to + * {@code Palette#optimize} because the same benchmark found the two cases where that price buys + * nothing at all — a section past the indirect ceiling comes out exactly as wide as it went in, and + * a section that is already packed was never going to move — and the guard turns those into + * {@code 185,1 µs} and {@code 31,8 µs}. What it costs is stated there too: {@code 24 %} on the case + * where the optimisation does narrow something. + *

+ * + * @param storage the storage of the chunk + * @param index the index of the section, counted from the bottom one + * @param generated the section the generator produced + */ + private void commitSection(BlockStorage storage, int index, GeneratorImpl.GenSection generated) { + final boolean producedNothing = generated.blocks().count() == 0 + && generated.biomes().count() == 0 + && generated.specials().isEmpty(); + + if (producedNothing && storage.shared(index)) { + return; + } + final Section section = storage.section(index); + + section.blockPalette().copyFrom(generated.blocks()); + section.biomePalette().copyFrom(generated.biomes()); + PaletteCompaction.packBlocks(section.blockPalette()); + PaletteCompaction.packBiomes(section.biomePalette()); + } + + /** + * Hands out the storage of a chunk, whatever kind of chunk it is. + *

+ * A chunk supplier is a setting of the instance and a caller is free to install one which does not + * produce a {@link FalcoChunk}. Rather than carrying two generation paths, a foreign chunk is + * wrapped in a {@link SectionBlockStorage} over its own live sections: that storage shares nothing + * and materialises nothing, so every decision below it collapses into the behaviour Minestom has, + * and the writes go straight into the sections of the chunk because the list holds the same + * {@code Section} references. + *

+ * + * @param chunk the chunk to reach the sections of + * @return the storage of the chunk + */ + private static BlockStorage storageOf(Chunk chunk) { + if (chunk instanceof FalcoChunk falcoChunk) { + return falcoChunk.storage(); + } + return new SectionBlockStorage(chunk.getMinSection(), chunk.getSections()); + } + + /** + * Writes the blocks of a generated section which need more than a palette entry. + *

+ * A palette holds a block state and nothing else, so a block which carries nbt, a handler or a + * block entity has to be written through the chunk as well. The generator collected those + * separately, keyed by a position relative to its section. + *

+ *

+ * The caller has to hold the write lock of the chunk. + *

+ * + * @param chunk the chunk which receives the blocks + * @param specials the blocks of the section which need their own entry + * @param sectionStartY the block Y at which the section begins + */ + private void writeSpecialBlocks(Chunk chunk, Int2ObjectMap specials, int sectionStartY) { + if (specials.isEmpty()) return; + for (Int2ObjectMap.Entry entry : specials.int2ObjectEntrySet()) { + final int position = entry.getIntKey(); + chunk.setBlock(CoordConversion.chunkBlockIndexGetX(position), + CoordConversion.chunkBlockIndexGetY(position) + sectionStartY, + CoordConversion.chunkBlockIndexGetZ(position), + entry.getValue()); + } + } + + /** + * Delivers the writes a generator made outside the chunk it was asked about. + *

+ * A fork which lands in a chunk that exists is applied right away, and one which lands in a + * chunk that does not is remembered until that chunk is created. Dropping the second kind is + * what would make a generator produce a different world depending on the order in which chunks + * were requested, which is the property a fork exists to avoid. + *

+ * + * @param chunk the chunk the generator was asked about + * @param unit the unit the generator wrote into + */ + private void applyForks(Chunk chunk, GeneratorImpl.UnitImpl unit) { + final int chunkX = chunk.getChunkX(); + final int chunkZ = chunk.getChunkZ(); + for (GeneratorImpl.UnitImpl fork : unit.forks()) { + if (!(fork.modifier() instanceof GeneratorImpl.AreaModifierImpl area)) continue; + for (GenerationUnit section : area.sections()) { + if (!(section.modifier() instanceof GeneratorImpl.SectionModifierImpl modifier)) continue; + if (modifier.genSection().blocks().count() == 0) continue; + final Point start = section.absoluteStart(); + if (start.chunkX() == chunkX && start.chunkZ() == chunkZ) { + applyFork(chunk, modifier); + continue; + } + final Chunk target = this.chunkAt.apply(start); + if (target != null && target.isLoaded()) { + applyFork(target, modifier); + target.sendChunk(); + continue; + } + this.generationForks.compute(CoordConversion.chunkIndex(start), (_, modifiers) -> { + final List pending = + modifiers == null ? new ArrayList<>() : modifiers; + pending.add(modifier); + return pending; + }); + } + } + } + + /** + * Applies the forks which were waiting for the given chunk to exist. + * + * @param chunk the chunk which just came into being + */ + public void applyPending(Chunk chunk) { + final long index = CoordConversion.chunkIndex(chunk.getChunkX(), chunk.getChunkZ()); + this.generationForks.compute(index, (_, modifiers) -> { + if (modifiers != null) { + for (GeneratorImpl.SectionModifierImpl modifier : modifiers) applyFork(chunk, modifier); + } + return null; + }); + } + + /** + * Writes one section of a fork into a chunk. + *

+ * A fork which produced nothing for this section returns before the chunk is touched, because + * {@code Chunk#getSectionAt} materialises on a lazy storage and a fork covers whole areas of which + * it usually fills a few sections. Minestom applies the same test at + * {@code InstanceContainer.java:434}. + *

+ *

+ * The honest statement about this guard is that it cannot fire today, and it is kept anyway rather + * than presented as a saving: {@link #applyForks(Chunk, GeneratorImpl.UnitImpl)} already drops a + * fork section whose palette is empty, and it is the only writer of the map + * {@link #applyPending(Chunk)} reads, so no empty section reaches this method by either route. + * It stays because this method is the point where the two routes converge and the only one that + * touches a section, and because a guard that lives where the materialisation happens does not + * depend on a caller remembering to filter. The special blocks are part of the condition for the + * same reason, even though a special block always writes its state into the palette as well. + *

+ * + * @param chunk the chunk which receives the blocks + * @param modifier the section of the fork to write + */ + private void applyFork(Chunk chunk, GeneratorImpl.SectionModifierImpl modifier) { + if (modifier.genSection().blocks().count() == 0 && modifier.genSection().specials().isEmpty()) { + return; + } + final int sectionStartY = modifier.start().blockY(); + chunk.lockWriteLock(); + try { + final Palette blocks = chunk.getSectionAt(sectionStartY).blockPalette(); + // A forked section marks an untouched position with a zero, so every block it does carry + // was stored with its state raised by one and has to be lowered again here. + modifier.genSection().blocks().getAllPresent((x, y, z, value) -> blocks.set(x, y, z, value - 1)); + writeSpecialBlocks(chunk, modifier.genSection().specials(), sectionStartY); + chunk.invalidate(); + } finally { + chunk.unlockWriteLock(); + } + } +} diff --git a/falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkLifecycle.java b/falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkLifecycle.java new file mode 100644 index 0000000..1a42ea3 --- /dev/null +++ b/falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkLifecycle.java @@ -0,0 +1,678 @@ +package net.onelitefeather.falco.instance; + +import net.minestom.server.MinecraftServer; +import net.minestom.server.coordinate.CoordConversion; +import net.minestom.server.entity.Entity; +import net.minestom.server.event.EventDispatcher; +import net.minestom.server.event.instance.InstanceChunkLoadEvent; +import net.minestom.server.event.instance.InstanceChunkUnloadEvent; +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.ChunkLoader; +import net.minestom.server.instance.ChunkViewerCache; +import net.minestom.server.instance.EntityTracker; +import net.minestom.server.instance.generator.Generator; +import net.minestom.server.network.packet.server.play.UnloadChunkPacket; +import net.minestom.server.utils.chunk.ChunkSupplier; +import org.jetbrains.annotations.ApiStatus; +import org.jetbrains.annotations.Nullable; + +import java.util.Objects; +import java.util.concurrent.CompletableFuture; +import java.util.function.Consumer; + +/** + * The {@link ChunkLifecycle} class is everything that happens to a chunk between not existing and + * not existing again: it is created, filled, published, marked and taken away. + *

+ * Every step is a method of its own and every one of them is reachable without the others. That is + * the whole point of the class and it is US-3.02: {@code publishChunk} and {@code completeLoad} were + * {@code private} methods of a class of more than 1 300 lines, so the only way to run them was to ask + * the instance for a chunk. The case they exist for cannot be arranged that way — a publish is + * refused when an unload claims the position while the loader is still working, and a caller driving + * the whole load path has no seam to interleave at. + *

+ * + *

What runs while a position is held, and what does not

+ *

+ * Putting a chunk into the registry and giving it a tick partition are one step, taken while the + * position is held, so an unload of the same position can only run entirely before or entirely after + * it. Splitting them is what lets Minestom delete a partition that is created a moment later, which + * leaves the chunk being ticked for the rest of the life of the server even though nothing else knows + * about it any more. + *

+ *

+ * On the publish side the loaded flag of the chunk is deliberately set outside the lock, + * and the asymmetry with {@link #unload(Chunk)}, which clears it from inside, is not an oversight. + * {@code Chunk#onLoad()} sets no flag: a chunk reports {@code isLoaded()} from the moment it is + * constructed, so nothing a reader of the instance can see depends on that hook having run yet. The + * unload hook does set the flag, and a chunk which has left the registry while still reporting itself + * as loaded is one every {@code ChunkUtils#isLoaded} check in Minestom believes in — which is why + * that one step is inside and the other is not. + *

+ *

+ * The packet, the event, the entities and the loader follow outside the lock in every case, because + * all four can call back into the instance, and holding a position while foreign code runs is how two + * chunks deadlock each other. What the removal step may do is stated on {@link ChunkRegistry} and + * applies in full, including to the hook a caller installs through + * {@link FalcoInstance#setChunkLifecycle(Consumer, Consumer)}. + *

+ * + *

Why this class speaks {@link Chunk} rather than {@link FalcoChunk}

+ *

+ * Because {@link FalcoInstance#setChunkLifecycle(Consumer, Consumer)} exists. A caller which owns + * another chunk type — a lighting chunk from {@code falco-light}, say — hands over the two + * {@code protected} hooks, and its chunks then take part in this lifecycle without ever being a + * {@link FalcoChunk}. Narrowing {@link #create(int, int)} or {@link #publish} to {@link FalcoChunk} + * would turn that supported case into a failure on the load path. + *

+ *

+ * This type is experimental. The instance module is new and its API may still change. + *

+ * + * + *

Where a listener of a chunk comes from

+ *

+ * From here, through {@link #addListener(ChunkLifecycleListener)}, and it is handed to the chunk in + * {@link #create(int, int)} rather than kept and consulted by this class. Only one of the five + * transitions a {@link ChunkLifecycleListener} reports is driven by this class at all — the publish; + * the tick and the block write reach a chunk without ever passing through a lifecycle, and a design + * which notified from here would have to leave those two out. + *

+ * + * @author TheMeinerLP + * @version 1.4.0 + * @since 0.4.0 + */ +@ApiStatus.Experimental +public final class ChunkLifecycle { + + /** + * The instance whose chunks these are, needed for the events, the entities and the supplier. + */ + private final FalcoInstance owner; + + /** + * Where a chunk goes when it is published and where it is taken from when it is unloaded. + */ + private final ChunkRegistry registry; + + /** + * Where a chunk is read from and where its removal is reported to. + */ + private final ChunkPersistence persistence; + + /** + * What fills a chunk no loader knows about. + */ + private final ChunkGeneration generation; + + /** + * The factory every chunk of this instance is created by. + *

+ * Volatile because the setter is public and unsynchronized while the load path reads the field + * from a chunk task on another thread. Without it the reader may not only miss the change, it may + * see a half-constructed supplier: the value is an arbitrary object handed in by a caller, and + * only a volatile write publishes that object safely. Synchronizing the setter instead would put + * a lock on the monitor of a public object, which is exactly what callers must not be able to + * hold against this instance. + *

+ */ + private volatile ChunkSupplier chunkSupplier = FalcoChunk::new; + + /** + * Whether a chunk which is asked for is loaded on demand. + */ + private volatile boolean autoChunkLoad = true; + + /** + * How a chunk of this instance is told that it was loaded, or null for the built-in way. + *

+ * {@code Chunk#onLoad()} and {@code Chunk#unload()} are {@code protected}, so this package can + * drive them only on {@link FalcoChunk}, a type it defines itself. A caller that owns another + * chunk type can reach both hooks and hands them over through + * {@link FalcoInstance#setChunkLifecycle(Consumer, Consumer)}. Null means the built-in pair, + * which requires a {@link FalcoChunk} exactly as before. + *

+ *

+ * Volatile for the same reason as {@link #chunkSupplier}: a caller object written by a public + * setter and read on the load path from another thread. + *

+ */ + private volatile @Nullable Consumer chunkLoaded; + + /** + * How a chunk of this instance is told that it left, or null for the built-in way. + * + * @see #chunkLoaded + */ + private volatile @Nullable Consumer chunkUnloaded; + + /** + * What every chunk of this instance is told about its own transitions, null while nobody listens. + *

+ * This is the instance-wide half of US-3.03; the per-chunk half is + * {@link FalcoChunk#addLifecycleListener(ChunkLifecycleListener)}. What is kept here is only the + * registration: {@link #create(int, int)} hands this listener to every chunk it builds, and every + * notification is then made by the chunk itself. A lifecycle which notified on behalf of its + * chunks would have to be reachable from a tick, and a tick has a chunk and no lifecycle. + *

+ *

+ * Volatile for the same reason as {@link #chunkSupplier}: a caller object written by a public + * setter and read on the load path from another thread. + *

+ */ + private volatile @Nullable ChunkLifecycleListener listener; + + /** + * Creates the lifecycle of the chunks of one instance. + * + * @param owner the instance whose chunks this lifecycle drives + * @param registry which chunk sits at which position, and which position is busy + * @param persistence where a chunk is read from and where its removal is reported to + * @param generation what fills a chunk no loader knows about + */ + public ChunkLifecycle(FalcoInstance owner, ChunkRegistry registry, ChunkPersistence persistence, + ChunkGeneration generation) { + this.owner = owner; + this.registry = registry; + this.persistence = persistence; + this.generation = generation; + } + + /** + * Hands back the chunk at the given position, loading it if it is not there yet. + *

+ * Two callers asking for the same chunk at the same time share one load: the first one to offer + * its future to {@link ChunkRegistry#acquire} performs the work, everyone else receives that + * same future. Which of the three cases a caller is in is the registry's decision and is + * explained there; this method only acts on the answer. + *

+ *

+ * The work itself starts after the decision, never inside it. A loader without parallel support + * runs on the calling thread, and starting it inside the decision would run it while the + * position is held, where a nested transition of the same position would deadlock. + *

+ *

+ * A failure completes the returned future exceptionally and stops there. It is deliberately not + * also pushed into the exception manager of the server the way the container does it, because a + * failure that is both reported and returned gets handled twice and logged twice. + *

+ * + * @param chunkX the chunk X + * @param chunkZ the chunk Z + * @return a future completed with the chunk, or completed exceptionally if it cannot be created + */ + public CompletableFuture retrieve(int chunkX, int chunkZ) { + final long index = CoordConversion.chunkIndex(chunkX, chunkZ); + final Chunk loaded = this.registry.chunk(index); + if (loaded != null) return CompletableFuture.completedFuture(loaded); + + final CompletableFuture own = new CompletableFuture<>(); + final ChunkRegistry.LoadSlot slot = this.registry.acquire(index, own); + switch (slot) { + case ChunkRegistry.LoadSlot.Loaded(Chunk cached) -> { + return CompletableFuture.completedFuture(cached); + } + case ChunkRegistry.LoadSlot.Running(CompletableFuture running) -> { + return running; + } + case ChunkRegistry.LoadSlot.Claimed ignored -> { + final ChunkLoader loader = this.persistence.loader(); + if (loader.supportsParallelLoading()) { + Thread.startVirtualThread(() -> completeLoad(index, chunkX, chunkZ, loader, own)); + } else { + // A loader without parallel support is read on the calling thread, which keeps a + // `loadChunk(…).join()` from a tick free of a thread hand-off it would only wait for. + completeLoad(index, chunkX, chunkZ, loader, own); + } + return own; + } + } + } + + /** + * Reads a chunk through the loader, publishes it and completes the waiting future. + *

+ * The chunk is produced first and published second, and the publish may be refused. Everything in + * between the two is the window in which an unload can decide that this chunk is not wanted any + * more; a load which is refused therefore has to undo itself rather than complain, which is what + * the discard below does. + *

+ *

+ * The two ends of that undo do not necessarily reach the same loader. The chunk is read through + * the loader handed in here, which {@link #retrieve(int, int)} captured before the load started, + * while {@link ChunkPersistence#unloaded(Chunk)} tells whichever loader is current when it runs. A + * {@link FalcoInstance#setChunkLoader(ChunkLoader)} in between therefore hands the discarded chunk + * to a loader that never produced it — which its own documentation permits, since Minestom gives a + * loader no way to tell its own chunks apart anyway. It is written down rather than fixed because + * changing it is a change of behaviour. + *

+ *

+ * The listener of this lifecycle is installed on both arms, and the two arms do it at different + * moments on purpose. A chunk this class builds itself receives it inside {@link #create(int, int)}, + * before the generator runs, because generation writes blocks. A chunk a {@link ChunkLoader} + * returns was built by that loader and never passed through {@link #create(int, int)}, so it is + * given the listener here — as late as the loader lets us and therefore after the loader has + * already written its blocks. That asymmetry is the loader's, not a choice: a loaded chunk has no + * moment before its blocks that this class can reach. + *

+ * + *

+ * What a listener which throws on this path costs. + * Everything after the chunk exists is foreign code that this class does not own: {@link #publish} + * ends in {@link FalcoChunk#notifyPublished()}, {@link #notifyLoaded(Chunk)} ends in + * {@link ChunkLifecycleListener#onLoad(ChunkLifecycleEvent)}, and the refused arm ends in + * {@link ChunkLifecycleListener#onUnload(ChunkLifecycleEvent)}. A throw out of any of the three + * used to leave {@code future} uncompleted, and an uncompleted future is not an error a caller can + * see — every {@code loadChunk(x, z).join()} on that position waits for the life of the process, + * while the chunk sits in the registry with a tick partition and no {@code InstanceChunkLoadEvent} + * ever fires. The trigger is not hypothetical: {@code ChunkLightListener#onLoad} reaches + * {@code ChunkLightScheduler#bind}, which throws when one scheduler is asked to serve two + * instances. + *

+ *

+ * The throw is therefore caught, handed to the waiting callers and rethrown unchanged. Both halves + * are deliberate. The future has to be completed because nothing else will complete it; the + * throwable has to keep going because it is a defect of the listener rather than a state of the + * world, and because rethrowing is what this method did before — on the calling thread it reaches + * whoever asked for the chunk, on a virtual thread of a parallel loader the default handler of + * that thread. Only the hang is new behaviour, and only in that it is gone. + *

+ *

+ * What the catch cannot repair is the state the chunk is left in. A throw on the publish arm or on + * the load arm happens after the chunk entered the registry, so the position carries a + * chunk which every later caller is handed while this load is reported as failed. A publish which + * threw inside the position lock itself — which {@link ChunkRegistry#publish} forbids and + * describes — additionally leaves the slot of the position standing; the entry in it is now a + * failed future rather than one nobody completes, so a later caller of that position is refused + * instead of blocked, which is less bad and still wrong. + *

+ * + * @param index the chunk index of the position, the key in the registry + * @param chunkX the chunk X + * @param chunkZ the chunk Z + * @param loader the loader the chunk is read from + * @param future the future handed to the callers waiting for this chunk + */ + public void completeLoad(long index, int chunkX, int chunkZ, ChunkLoader loader, + CompletableFuture future) { + final Chunk managed; + try { + Chunk chunk = loader.loadChunk(this.owner, chunkX, chunkZ); + if (chunk == null) { + chunk = create(chunkX, chunkZ); + chunk.onGenerate(); + } else { + // The loader built this chunk itself, so create() never saw it. Without this line a + // world read from disk would report no transition at all while a freshly generated + // neighbour reports all five. + installListener(chunk); + } + managed = requireManaged(chunk); + } catch (Throwable throwable) { + this.registry.release(index, future); + future.completeExceptionally(throwable); + return; + } + try { + if (!publish(index, managed, future)) { + // The chunk was never part of this instance, so there is no registry entry and no + // partition to clean up. The callers are told before the chunk is: a discard which + // took this position completed this future already, but one which took it and was + // followed by a new load did not, and then this line is the only completion there is. + future.completeExceptionally(new FalcoInstanceException("the chunk " + chunkX + ":" + chunkZ + + " was unloaded while it was being loaded, so the loaded chunk was discarded")); + try { + notifyUnloaded(managed); + } finally { + // In a finally because the line above is foreign code: the loader created this + // chunk and may hold bookkeeping for it, which its own documentation allows for + // explicitly, and a listener which throws must not turn that into a leak. + this.persistence.unloaded(managed); + } + return; + } + notifyLoaded(managed); + } catch (Throwable throwable) { + // The waiting callers first, the throw afterwards, both for the reasons above. Completing + // is a no-op when one of the two arms already completed this future, which is what makes + // it safe to do here for every throw of the stretch rather than per arm. + future.completeExceptionally(throwable); + throw throwable; + } + future.complete(managed); + EventDispatcher.call(new InstanceChunkLoadEvent(this.owner, managed)); + } + + /** + * Makes a freshly built chunk part of this instance, unless somebody claimed its position. + *

+ * The step handed to the registry has no foreign code in it, but that is a property of this + * method rather than a rule of the registry; {@link ChunkRegistry} states what a step handed to it + * may do, and the removal step of {@link #unload(Chunk)} is bound by exactly the same rules. + *

+ * + * @param index the chunk index of the position + * @param chunk the chunk to publish + * @param future the future of this load, which has to still be the entry of the position + * @return true if the chunk is now part of this instance, false if the load was claimed + */ + public boolean publish(long index, Chunk chunk, CompletableFuture future) { + final boolean published = this.registry.publish(index, chunk, future, + inLock -> MinecraftServer.process().dispatcher().createPartition(inLock)); + // Outside the step and therefore outside the position lock: a listener may call back into + // the instance, and the registry forbids exactly that from inside. + if (published && chunk instanceof FalcoChunk falcoChunk) falcoChunk.notifyPublished(); + return published; + } + + /** + * Takes the slot of a running load so its chunk never reaches this instance. + *

+ * Removing the entry is the whole claim: the loading thread publishes its chunk only while its + * own future is still the entry of the position, so a load which finds the slot empty or taken + * knows that somebody decided its result is no longer wanted. The waiting callers are told with + * a failure rather than with the chunk, because a chunk which is handed back after it was + * discarded looks usable and is not. + *

+ * + * @param index the chunk index of the position whose load is claimed + */ + public void discard(long index) { + final CompletableFuture running = this.registry.discard(index); + if (running == null) return; + running.completeExceptionally(new FalcoInstanceException("the chunk " + + CoordConversion.chunkIndexGetX(index) + ":" + CoordConversion.chunkIndexGetZ(index) + + " was unloaded while it was being loaded, so the load was cancelled")); + } + + /** + * Hands this lifecycle's listener to a chunk that can carry one. + *

+ * Two conditions have to hold and neither is an accident. There has to be a listener at all — + * the common case is that there is none, and the call then costs one field read. And the chunk + * has to be a {@link FalcoChunk}, because carrying a listener is what that type adds; a chunk + * from a foreign supplier takes part in the lifecycle without reporting it, which is a + * limitation of the supplier rather than of this class. + *

+ *

+ * Extracted because the two arms of {@link #retrieve(int, int)} need it at different moments and + * a copy in each would be a place for them to drift apart. The moments themselves are documented + * where they are chosen, not here. + *

+ * + * @param chunk the chunk to install the listener on + */ + private void installListener(Chunk chunk) { + final ChunkLifecycleListener installed = this.listener; + + if (installed != null && chunk instanceof FalcoChunk falcoChunk) { + falcoChunk.addLifecycleListener(installed); + } + } + + /** + * Creates a chunk through the chunk supplier of this instance and generates it. + *

+ * This is the path a chunk takes which no {@link ChunkLoader} knows about. Without a generator the + * chunk stays empty, which is a world made of air rather than a failure. + *

+ *

+ * The chunk type is not checked here. A supplier may legitimately produce something this package + * cannot drive on its own, and whether that is acceptable depends on the pair of hooks a caller + * installed; {@link #completeLoad} is where that question is answered, and it is answered once. + *

+ * + * @param chunkX the chunk X + * @param chunkZ the chunk Z + * @return the created chunk + * @throws FalcoInstanceException if the chunk supplier returned null + */ + public Chunk create(int chunkX, int chunkZ) { + final Chunk chunk = this.chunkSupplier.createChunk(this.owner, chunkX, chunkZ); + if (chunk == null) { + throw new FalcoInstanceException("the chunk supplier returned null for chunk " + chunkX + ":" + chunkZ); + } + // Before the generator runs, not after it: generation writes the blocks which carry a + // handler through Chunk#setBlock, and a listener registered afterwards would miss them. + installListener(chunk); + final Generator current = this.generation.generator(); + if (current != null && chunk.shouldGenerate()) { + this.generation.apply(chunk, current); + this.owner.refreshLastBlockChangeTime(); + } else { + this.generation.applyPending(chunk); + } + return chunk; + } + + /** + * Removes a chunk from this instance. + *

+ * Taking the chunk out of the registry, clearing its loaded flag and deleting its tick partition + * are one step, taken while the position of the chunk is held, so a load which is publishing the + * same position cannot interleave with it. Everything else — the packet, the event, the entities + * and the loader — follows outside, because all four can call back into the instance and holding a + * position while foreign code runs is how two chunks deadlock each other. + *

+ *

+ * A running load is not cancelled here and not waited for either, and that is not an omission: a + * position which is loading has no chunk in the registry, so a chunk a caller can hand to this + * method is never the one being loaded. It is either the chunk of that position, which the atomic + * step below removes, or a chunk of an earlier life of that position, which was already unloaded + * and is refused by the first line. Cancelling a load needs a position rather than a chunk, and + * {@link #discard(long)} is where that happens. + *

+ *

+ * Unloading the same chunk twice does nothing the second time, which makes this usable in a + * cleanup path that may run more than once. + *

+ *

+ * The very last step gives the viewer cache entry of the position back, which is US-3.01. The + * constructor of every {@link Chunk} takes one out of a {@code computeIfAbsent} in the entity + * tracker and Minestom never removes it again, so a world which streams chunks keeps one entry + * per position it has ever visited for the life of the process. It runs after everything else + * because the four steps above still send packets to, and remove entities from, exactly those + * viewers. Why the removal needs a class in a package of Minestom is stated on + * {@link ChunkViewerCache}. + *

+ * + * @param chunk the chunk to remove, which this instance has to be able to drive + * @throws FalcoInstanceException if the chunk is not a {@link FalcoChunk} and no lifecycle pair + * was installed + */ + public void unload(Chunk chunk) { + if (!chunk.isLoaded()) return; + final Chunk managed = requireManaged(chunk); + final int chunkX = managed.getChunkX(); + final int chunkZ = managed.getChunkZ(); + final long index = CoordConversion.chunkIndex(chunkX, chunkZ); + final boolean removed = this.registry.remove(index, managed, unloaded -> { + notifyUnloaded(unloaded); + MinecraftServer.process().dispatcher().deletePartition(unloaded); + }); + + if (!removed) return; + managed.sendPacketToViewers(new UnloadChunkPacket(chunkX, chunkZ)); + EventDispatcher.call(new InstanceChunkUnloadEvent(this.owner, managed)); + this.owner.getEntityTracker().chunkEntities(chunkX, chunkZ, EntityTracker.Target.ENTITIES) + .forEach(Entity::remove); + this.persistence.unloaded(managed); + // Last, because everything above may still want to reach the viewers of this chunk. The view + // object stays alive in the chunk itself; what goes is the entry that kept it findable, which + // is what nothing in Minestom ever removes. + ChunkViewerCache.release(this.owner, chunkX, chunkZ); + } + + /** + * Hands out what fills a chunk no loader knows about. + *

+ * This is the only route to {@link ChunkGeneration} there is, and that is the point rather than an + * inconvenience. A chunk is generated exactly once and that once is inside its load, so generation + * is a collaborator of this class; giving {@link FalcoInstance} a field for it would have made it a + * fifth part of a facade that holds four, which {@code InstanceFacadeTest} refuses. The three + * members of {@link FalcoInstance} that still speak about generation — + * {@link FalcoInstance#generator()}, {@link FalcoInstance#setGenerator(Generator)} and + * {@link FalcoInstance#generateChunk(int, int, Generator)} — reach it through here. + *

+ * + * @return the generation side of this lifecycle + * @since 0.4.0 + */ + public ChunkGeneration generation() { + return this.generation; + } + + /** + * Adds a listener every chunk this lifecycle creates from now on is given. + *

+ * A second listener composes with the first through {@link ChunkLifecycleListener#of}, so two + * extensions can live beside each other on the same chunk, which is what US-3.03 asks for and + * what a superclass could never provide. + *

+ *

+ * Chunks which already exist are deliberately not touched. A listener is handed over in + * {@link #create(int, int)}, before the generator runs, so a chunk either had the listener for + * its whole life or never had it — a chunk that received one halfway through would report a + * transition whose counterpart the listener never saw. A caller which wants a listener on a chunk + * that is already loaded adds it to that chunk through + * {@link FalcoChunk#addLifecycleListener(ChunkLifecycleListener)} and knows what it is asking for. + *

+ *

+ * Registration is not atomic, for the reason given on + * {@link FalcoChunk#addLifecycleListener(ChunkLifecycleListener)}: two threads registering at the + * same moment can lose one of the two. This is a setup call and belongs before the first chunk of + * the instance is asked for. + *

+ * + * @param listener the listener every chunk created from now on is given + * @throws NullPointerException if the listener is null + * @since 0.4.0 + */ + public void addListener(ChunkLifecycleListener listener) { + final ChunkLifecycleListener current = this.listener; + this.listener = current == null ? Objects.requireNonNull(listener, + "the listener cannot be null") : ChunkLifecycleListener.of(current, listener); + } + + /** + * Hands out what every chunk created by this lifecycle is given. + * + * @return the listener of this lifecycle, or null if nothing listens + * @since 0.4.0 + */ + public @Nullable ChunkLifecycleListener listener() { + return this.listener; + } + + /** + * Hands out what produces the chunk objects of this instance. + * + * @return the current chunk supplier + */ + public ChunkSupplier supplier() { + return this.chunkSupplier; + } + + /** + * Changes what produces the chunk objects of this instance. + * + * @param supplier the new chunk supplier + * @throws NullPointerException if the supplier is null + */ + public void supplier(ChunkSupplier supplier) { + this.chunkSupplier = Objects.requireNonNull(supplier, "the chunk supplier cannot be null"); + } + + /** + * Reports whether a chunk which is asked for is loaded on demand. + * + * @return true if chunks are loaded on demand + */ + public boolean autoLoad() { + return this.autoChunkLoad; + } + + /** + * Sets whether a chunk which is asked for is loaded on demand. + * + * @param enable true to load chunks on demand + */ + public void autoLoad(boolean enable) { + this.autoChunkLoad = enable; + } + + /** + * Says how a chunk of this instance is told that it was loaded and that it left. + *

+ * Both halves are set at once so the pair cannot end up half configured. What a caller may write + * into either of them differs, and the difference is documented on + * {@link FalcoInstance#setChunkLifecycle(Consumer, Consumer)}, which is the public door to this. + *

+ * + * @param onLoaded what tells a chunk that it is part of this instance + * @param onUnloaded what tells a chunk that it left this instance + * @throws NullPointerException if either half is null + */ + public void hooks(Consumer onLoaded, Consumer onUnloaded) { + Objects.requireNonNull(onLoaded, "the loaded half of the lifecycle cannot be null"); + Objects.requireNonNull(onUnloaded, "the unloaded half of the lifecycle cannot be null"); + this.chunkLoaded = onLoaded; + this.chunkUnloaded = onUnloaded; + } + + /** + * Checks that a chunk is one this instance can manage. + *

+ * A chunk of any other type would be accepted by everything except the unload path, where the + * {@code protected} lifecycle hooks are out of reach, so it would silently keep reporting itself + * as loaded forever. Refusing it here names the cause at the point where the wrong supplier was + * used. + *

+ * + * @param chunk the chunk to check + * @return the same chunk + * @throws FalcoInstanceException if the chunk is not a {@link FalcoChunk} and no lifecycle pair + * was installed + */ + private Chunk requireManaged(Chunk chunk) { + if (this.chunkLoaded == null || this.chunkUnloaded == null) { + if (chunk instanceof FalcoChunk falcoChunk) return falcoChunk; + throw new FalcoInstanceException("this instance only manages " + FalcoChunk.class.getName() + + ", but its chunk supplier produced a " + chunk.getClass().getName() + + "; the lifecycle hooks of any other chunk cannot be reached from this package." + + " Configure setChunkLifecycle if you own the chunk type and can reach them"); + } + return chunk; + } + + /** + * Tells a chunk that it is now part of this instance. + * + * @param chunk the chunk which finished loading + */ + private void notifyLoaded(Chunk chunk) { + final @Nullable Consumer configured = this.chunkLoaded; + + if (configured == null) { + ((FalcoChunk) chunk).markLoaded(); + return; + } + configured.accept(chunk); + } + + /** + * Tells a chunk that it is no longer part of this instance. + * + * @param chunk the chunk which left the instance + */ + private void notifyUnloaded(Chunk chunk) { + final @Nullable Consumer configured = this.chunkUnloaded; + + if (configured == null) { + ((FalcoChunk) chunk).markUnloaded(); + return; + } + configured.accept(chunk); + } +} diff --git a/falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkLifecycleEvent.java b/falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkLifecycleEvent.java new file mode 100644 index 0000000..5b4b8dc --- /dev/null +++ b/falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkLifecycleEvent.java @@ -0,0 +1,32 @@ +package net.onelitefeather.falco.instance; + +import org.jetbrains.annotations.ApiStatus; + +/** + * The {@link ChunkLifecycleEvent} record is what a {@link ChunkLifecycleListener} is told about a + * transition of a chunk. + *

+ * It is a record with two components rather than four method parameters because a transition will + * grow things worth reporting and a parameter list cannot. It is built by the chunk, once per + * transition, and only when a listener is installed — {@link FalcoChunk} checks the listener + * field before it constructs anything, which is what makes a chunk nobody listens to free. + * {@code ChunkLifecycleAllocationTest} measures both halves of that sentence. + *

+ *

+ * The instance is not a component: it is {@code chunk.getInstance()} and duplicating it would make + * the record wider for every transition to save one call on the few that need it. + *

+ *

+ * This type is experimental. The instance module is new and its API may still change. + *

+ * + * @param chunk the chunk the transition happened to + * @param time the tick time in milliseconds for {@link ChunkLifecycleListener#onTick}, and + * {@code 0} for every other transition, because the other three do not happen at a tick + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ApiStatus.Experimental +public record ChunkLifecycleEvent(FalcoChunk chunk, long time) { +} diff --git a/falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkLifecycleListener.java b/falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkLifecycleListener.java new file mode 100644 index 0000000..bba9cc4 --- /dev/null +++ b/falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkLifecycleListener.java @@ -0,0 +1,258 @@ +package net.onelitefeather.falco.instance; + +import net.minestom.server.instance.block.Block; +import org.jetbrains.annotations.ApiStatus; + +import java.util.Objects; + +/** + * The {@link ChunkLifecycleListener} interface is how something is told what happens to a chunk, + * without being that chunk. + *

+ * Before this interface a chunk had exactly one extension point and it was its superclass. + * {@code FalcoLightingChunk} occupied it, which is why Falco's light and Falco's instance could not + * be used together at all — {@code FalcoChunk} and {@code FalcoLightingChunk} both extended + * {@code DynamicChunk}, a class has one superclass, and a server had to pick one of the two. A + * listener is a field, and a field composes. + *

+ * + *

Why the block change is not an event

+ *

+ * Four of these five methods happen once in the life of a chunk or once per tick, and they carry a + * {@link ChunkLifecycleEvent}. {@link #onBlockChange} happens once per block written and takes + * primitives, because an event object there would be an allocation on the hottest path of this + * module. The asymmetry is deliberate and it is measured rather than argued: see + * {@code ChunkLifecycleAllocationTest}. + *

+ *

+ * Every method is a default doing nothing, so a listener implements what it cares about. Every one of + * them runs on the thread that caused the transition, under whatever lock that thread holds — a + * listener which blocks blocks a chunk load, a tick or a block write. Which lock that is, is stated + * per method, because the five are not the same — and, where the two arms below differ, per arm. + *

+ * + *

Two instances drive these five, and they do not hold the same locks

+ *

+ * A {@link FalcoChunk} is reached through two doors. {@link FalcoInstance} drives it through + * {@link ChunkLifecycle}, and an {@code InstanceContainer} drives it through the {@code protected} + * hooks of {@code Chunk} — which is not a corner case but the arrangement US-3.06 was built for: + * {@code FalcoLightingChunk} is a {@link FalcoChunk} and is meant to run in a plain container, where + * its listener is the light engine. The two arms differ in what a listener is allowed to do, and the + * difference is stated per method rather than averaged into one sentence. + *

+ *

+ * Written short: only {@link #onPublish} is missing on the container arm, and everything else that + * differs makes the container arm the stricter of the two — it holds the monitor of the + * instance where {@link FalcoInstance} holds a per-chunk lock or nothing. A listener written for the + * container arm therefore works on both, and that is the one to write. + *

+ *

+ * This type is experimental. The instance module is new and its API may still change. + *

+ * + * @author TheMeinerLP + * @version 1.2.0 + * @since 0.4.0 + */ +@ApiStatus.Experimental +public interface ChunkLifecycleListener { + + /** + * Reports that a chunk has become part of its instance and has a tick partition. + *

+ * Fired after the position of the chunk was released and therefore outside the lock of that + * position, which is what makes it safe for a listener to call back into the instance. + *

+ *

+ * This is the one of the five which only a {@link FalcoInstance} ever fires. Publishing is + * a step of {@link ChunkLifecycle} and nothing on a chunk marks it, so a chunk driven by an + * {@code InstanceContainer} is told that it loaded and never that it was published. A listener + * which wants one moment per chunk and has to work in both takes {@link #onLoad}. + *

+ *

+ * A throw out of this method fails the load it belongs to: {@link ChunkLifecycle#completeLoad} + * hands the throwable to every caller waiting on that position and rethrows it. The chunk stays + * where it is — it entered the registry and got its tick partition before this call — so the + * position ends up carrying a chunk which a load reported as failed. There is no arrangement in + * which throwing here is useful, and this is what it costs. + *

+ * + * @param event what happened, to which chunk + */ + default void onPublish(ChunkLifecycleEvent event) { + } + + /** + * Reports that a chunk has finished loading and is now reported as loaded. + *

+ * Under a {@link FalcoInstance} this is fired after {@link #onPublish}, outside the lock of the + * position as well, and before the {@code InstanceChunkLoadEvent} of the server reaches anybody. + *

+ *

+ * Under an {@code InstanceContainer} there is no {@link #onPublish} before it and no position of + * a {@link ChunkRegistry} in the picture at all: the container calls the {@code protected} + * {@code Chunk#onLoad()} hook itself, from {@code retrieveChunk}, after the chunk is in its map + * and before it completes the future and dispatches the event. That call holds no lock either — + * {@code retrieveChunk} is not {@code synchronized}, unlike the unload — and it runs on whichever + * thread read the chunk, which for a loader with parallel support is a virtual thread of its own. + *

+ *

+ * So neither arm holds a lock here, and a listener may call back into its instance. What both + * arms do pay is time: this call sits between the chunk being ready and the caller of + * {@code loadChunk} being told, so a slow listener slows down every chunk load. + *

+ *

+ * A throw is paid for on both arms as well, and differently. Under an {@code InstanceContainer} + * it leaves {@code retrieveChunk} before the future is completed and before the load event is + * dispatched. Under a {@link FalcoInstance} it is caught once, handed to every caller waiting on + * that position and rethrown unchanged — the load fails, the chunk stays published, and no + * {@code InstanceChunkLoadEvent} is dispatched for it. Both arms leave a chunk which is in its + * instance and which nobody was told about; neither of them undoes the load. + *

+ * + * @param event what happened, to which chunk + */ + default void onLoad(ChunkLifecycleEvent event) { + } + + /** + * Reports that a chunk was ticked. + *

+ * Fired on every tick of the chunk, before the block handlers of that chunk run and regardless of + * whether the chunk holds any, so a listener which needs a heartbeat gets one from every chunk + * rather than only from the ones that carry a block entity. + *

+ *

+ * A tick holds no lock of the chunk at all — {@code Chunk#tick} says of itself that it "doesn't + * necessary have to be thread-safe" — so a listener which reads blocks here has to take the read + * lock the way any other reader would. + *

+ *

+ * This is the one method where the two arms are the same call. A tick reaches a chunk from the + * {@code ThreadDispatcher} of the server and never through its instance, so it looks identical + * whether a {@link FalcoInstance} or an {@code InstanceContainer} owns the chunk. + *

+ * + * @param event what happened, to which chunk, and at which tick time + */ + default void onTick(ChunkLifecycleEvent event) { + } + + /** + * Reports that a chunk is no longer part of its instance. + *

+ * This is the one of the five which always runs under a lock, on both arms, and they are not + * the same lock. Under a {@link FalcoInstance} the position of the chunk is held by + * {@link ChunkRegistry}, because clearing the loaded flag of a chunk and taking it out of the + * registry are deliberately one step. Everything {@link ChunkRegistry} says about a step handed + * to it therefore applies to a listener here as well: short, non-blocking, no call back into the + * instance and no exception, because a throwing listener leaves the chunk removed and only half + * unloaded. + *

+ *

+ * Under an {@code InstanceContainer} there is no position lock, and the constraint is if anything + * tighter. {@code InstanceContainer#unloadChunk} is {@code synchronized} on the instance for its + * whole body, so the monitor of the instance is held while this runs; it has also already sent + * the unload packet, dispatched its event, removed the entities and taken the chunk out of its + * map before it calls the hook, so a listener asking that instance for this chunk is told there + * is none. Calling back into the instance from here does not deadlock the calling thread, since + * an intrinsic monitor is reentrant, but every other thread waiting on a {@code synchronized} + * method of that instance waits for the listener to return. The rule that holds on both arms is + * the short one: report, and return. + *

+ *

+ * The single exception to the sentence above is the discarded load on the {@link FalcoInstance} + * arm, which holds nothing because the position was released before the chunk was disowned — see + * {@link ChunkLifecycle#completeLoad}. A listener may not tell that case apart and must not try. + * It is also the one arm on which a throw does not cost the caller anything: the callers of that + * load are told it failed before this method is reached, and the loader is told about the + * discarded chunk from a {@code finally} afterwards. The throw itself still leaves the load path + * for whoever installed the listener. + *

+ *

+ * It is also the one which can arrive without {@link #onPublish} and {@link #onLoad} ever having + * arrived. A chunk whose position was claimed while its loader was still working is told that it + * was unloaded so that whatever it holds is released, even though it never became part of the + * instance — see {@link ChunkLifecycle#completeLoad}. A listener which tears down state it built + * in {@link #onLoad} has to survive being asked to tear down nothing. + *

+ * + * @param event what happened, to which chunk + */ + default void onUnload(ChunkLifecycleEvent event) { + } + + /** + * Reports that one block of a chunk was written. + *

+ * Fired after the block is in the storage and after the handlers of the old and the new block + * ran, holding the write lock of the chunk. The position is world coordinates, as the chunk + * received them. + *

+ *

+ * That write lock is all a {@link FalcoInstance} holds, which is the point of {@link BlockWriter} + * — a write into one chunk does not stop a write into another. An {@code InstanceContainer} + * reaches the same line through its {@code private synchronized UNSAFE_setBlock} and therefore + * holds the monitor of the whole instance on top of it. A listener here is on the hottest path of + * this module either way and belongs nowhere near a blocking call. + *

+ * + * @param chunk the chunk which received the block + * @param x the block X + * @param y the block Y + * @param z the block Z + * @param block the block which was written + */ + default void onBlockChange(FalcoChunk chunk, int x, int y, int z, Block block) { + } + + /** + * Composes two listeners into one which notifies both, in order. + *

+ * Composition rather than a list because a list is an object per chunk and an iterator per + * transition, and almost every chunk of a world has no listener at all. Two listeners nest into + * one object, three into two, and the allocation happens once, at registration. + *

+ * + * @param first the listener notified first + * @param second the listener notified second + * @return a listener which notifies both + * @throws NullPointerException if either listener is null + */ + static ChunkLifecycleListener of(ChunkLifecycleListener first, ChunkLifecycleListener second) { + Objects.requireNonNull(first, "the first listener cannot be null"); + Objects.requireNonNull(second, "the second listener cannot be null"); + return new ChunkLifecycleListener() { + + @Override + public void onPublish(ChunkLifecycleEvent event) { + first.onPublish(event); + second.onPublish(event); + } + + @Override + public void onLoad(ChunkLifecycleEvent event) { + first.onLoad(event); + second.onLoad(event); + } + + @Override + public void onTick(ChunkLifecycleEvent event) { + first.onTick(event); + second.onTick(event); + } + + @Override + public void onUnload(ChunkLifecycleEvent event) { + first.onUnload(event); + second.onUnload(event); + } + + @Override + public void onBlockChange(FalcoChunk chunk, int x, int y, int z, Block block) { + first.onBlockChange(chunk, x, y, z, block); + second.onBlockChange(chunk, x, y, z, block); + } + }; + } +} diff --git a/falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkPersistence.java b/falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkPersistence.java new file mode 100644 index 0000000..58764bd --- /dev/null +++ b/falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkPersistence.java @@ -0,0 +1,262 @@ +package net.onelitefeather.falco.instance; + +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.ChunkLoader; +import net.minestom.server.instance.Instance; +import org.jetbrains.annotations.ApiStatus; +import org.jetbrains.annotations.Nullable; + +import java.util.List; +import java.util.Objects; +import java.util.concurrent.CompletableFuture; + +/** + * The {@link ChunkPersistence} class is everything a Falco instance does with a {@link ChunkLoader}. + *

+ * Four save entry points, one read and one unload notification, and the decision on which thread each + * of them runs. That decision is the only piece of judgement in this class and it belongs to the + * loader: a loader which reports {@code supportsParallelSaving()} is moved onto a virtual thread, and + * one which does not runs where it was called, so a {@code saveInstance().join()} from a tick is not + * a thread hand-off the caller only waits for. + *

+ *

+ * A failure completes the returned future exceptionally and stops there. It is deliberately not also + * pushed into the exception manager of the server the way {@code InstanceContainer} does it, because + * a failure that is both reported and returned gets handled twice and logged twice — which is + * NFR-005 for the save direction. + *

+ *

+ * This type was carved out of {@link FalcoInstance} and nothing about the four save paths changed in + * the move. The loader field is still {@code volatile} for the same reason it was there: it is + * written by a public unsynchronized setter and read on the load path from another thread, and the + * value is an object handed in by a caller whose construction has to be visible to that reader. + *

+ * + *

Why the two shutdown settings live here

+ *

+ * {@link #saveOnShutdown()} and {@link #ownsLoader()} steer {@link FalcoInstance#shutdown(net.minestom.server.instance.InstanceManager)}, + * so at first sight they look like settings of the instance, and they were fields of it until stage 3 + * asserted that the facade holds nothing but its four parts. They are not arbitrary refugees from that + * assertion: both are questions about the loader and about nothing else — whether the chunks are + * written through it before the world goes away, and whether it is closed afterwards — and this is the + * class that owns the loader. An instance without a loader answers both of them the same way whatever + * they are set to. + *

+ *

+ * They are deliberately not reachable from {@link FalcoInstance}, which has no {@code persistence()} + * door. That keeps them what they were before the move: values a caller sets on + * {@code FalcoInstance.Builder} while the world is being built, and not a switch that can be flipped + * from under a running shutdown. + *

+ *

+ * What the move did not do is worth being exact about, because the commit that made it could + * be read as claiming more. No method of this class consults either setting; the only reader of both + * is {@code FalcoInstance#shutdown}, and the shutdown sequence stays there because the save has to + * happen before the unregister and the close after it — an order about the instance, not about the + * loader. So the two values were re-homed, not consumed here, and the facade still acts on them one + * hop away. Bringing the sequence into this class would move behaviour rather than structure, which + * stage 3 does not do; if a later change wants that, it is a decision of its own and the argument for + * it is that these two accessors would then have a caller inside their own class. + *

+ *

+ * This type is experimental. The instance module is new and its API may still change. + *

+ * + * @author TheMeinerLP + * @version 1.1.1 + * @since 0.4.0 + */ +@ApiStatus.Experimental +public final class ChunkPersistence { + + /** + * The loader chunks are read from and written to, never null. + */ + private volatile ChunkLoader chunkLoader; + + /** + * Whether the shutdown of the instance saves the chunks before it unregisters. + *

+ * Volatile for the same reason as {@link #chunkLoader}: written by a public unsynchronized setter + * and read on a path that may run on another thread. + *

+ */ + private volatile boolean saveOnShutdown = true; + + /** + * Whether the shutdown of the instance closes the loader, if the loader can be closed. + * + * @see #saveOnShutdown + */ + private volatile boolean ownsLoader; + + /** + * Creates a persistence over a loader. + * + * @param loader the loader chunks are read from and written to, null for a loader which loads and + * saves nothing + */ + public ChunkPersistence(@Nullable ChunkLoader loader) { + this.chunkLoader = Objects.requireNonNullElseGet(loader, ChunkLoader::noop); + } + + /** + * Returns the loader chunks are read from and written to. + * + * @return the current chunk loader + */ + public ChunkLoader loader() { + return this.chunkLoader; + } + + /** + * Changes the loader chunks are read from and written to. + *

+ * Chunks which are already loaded are not affected, and {@code ChunkLoader#loadInstance} is not + * called again — it belongs to the construction of the instance, and calling it on a world which + * already has chunks would overwrite live state with what is on disk. + *

+ * + * @param loader the new chunk loader + * @throws NullPointerException if the loader is null + */ + public void loader(ChunkLoader loader) { + this.chunkLoader = Objects.requireNonNull(loader, "the chunk loader cannot be null"); + } + + /** + * Reports whether the shutdown of the instance saves the chunks before it unregisters. + * + * @return true if the shutdown saves first + * @since 0.4.0 + */ + public boolean saveOnShutdown() { + return this.saveOnShutdown; + } + + /** + * Sets whether the shutdown of the instance saves the chunks before it unregisters. + *

+ * The default is true, and the asymmetry is deliberate: saving a world nobody changed costs time, + * while not saving one that was changed costs the changes. + *

+ * + * @param enable true if the shutdown saves before it unregisters + * @since 0.4.0 + */ + public void saveOnShutdown(boolean enable) { + this.saveOnShutdown = enable; + } + + /** + * Reports whether the shutdown of the instance closes the loader. + * + * @return true if the instance closes the loader when it shuts down + * @since 0.4.0 + */ + public boolean ownsLoader() { + return this.ownsLoader; + } + + /** + * Sets whether the shutdown of the instance closes the loader. + *

+ * The default is false, because a loader is usually shared: the overworld and the nether of one + * world are two instances on one loader, and the first of them to shut down must not close it + * under the second. + *

+ * + * @param owns true if the instance closes the loader when it shuts down + * @since 0.4.0 + */ + public void ownsLoader(boolean owns) { + this.ownsLoader = owns; + } + + /** + * Reads a chunk through the current loader. + * + * @param instance the instance the chunk is read for + * @param chunkX the chunk X + * @param chunkZ the chunk Z + * @return the chunk the loader produced, or null if it knows nothing about that position + */ + public @Nullable Chunk read(Instance instance, int chunkX, int chunkZ) { + return this.chunkLoader.loadChunk(instance, chunkX, chunkZ); + } + + /** + * Tells the loader that a chunk is no longer part of its instance. + *

+ * Called for a chunk which was unloaded and for a chunk whose load was discarded before it was + * ever published: the loader created it and may hold bookkeeping for it, which its own + * documentation allows for explicitly. + *

+ * + * @param chunk the chunk which left the instance + */ + public void unloaded(Chunk chunk) { + this.chunkLoader.unloadChunk(chunk); + } + + /** + * Saves the instance itself. + * + * @param instance the instance to save + * @return a future completed once the work is done, completed exceptionally if it threw + */ + public CompletableFuture saveInstance(Instance instance) { + final ChunkLoader loader = this.chunkLoader; + return run(loader.supportsParallelSaving(), () -> loader.saveInstance(instance)); + } + + /** + * Saves one chunk. + * + * @param chunk the chunk to save + * @return a future completed once the work is done, completed exceptionally if it threw + */ + public CompletableFuture saveChunk(Chunk chunk) { + final ChunkLoader loader = this.chunkLoader; + return run(loader.supportsParallelSaving(), () -> loader.saveChunk(chunk)); + } + + /** + * Saves a batch of chunks. + * + * @param chunks the chunks to save + * @return a future completed once the work is done, completed exceptionally if it threw + */ + public CompletableFuture saveChunks(List chunks) { + final ChunkLoader loader = this.chunkLoader; + return run(loader.supportsParallelSaving(), () -> loader.saveChunks(chunks)); + } + + /** + * Runs a save either on the calling thread or on a virtual thread. + * + * @param parallel true to move the work off the calling thread + * @param save the work to perform + * @return a future completed once the work is done, completed exceptionally if it threw + */ + private CompletableFuture run(boolean parallel, Runnable save) { + if (!parallel) { + try { + save.run(); + return CompletableFuture.completedFuture(null); + } catch (Throwable throwable) { + return CompletableFuture.failedFuture(throwable); + } + } + final CompletableFuture future = new CompletableFuture<>(); + Thread.startVirtualThread(() -> { + try { + save.run(); + future.complete(null); + } catch (Throwable throwable) { + future.completeExceptionally(throwable); + } + }); + return future; + } +} diff --git a/falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkRegistry.java b/falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkRegistry.java new file mode 100644 index 0000000..a1ac37d --- /dev/null +++ b/falco-instance/src/main/java/net/onelitefeather/falco/instance/ChunkRegistry.java @@ -0,0 +1,431 @@ +package net.onelitefeather.falco.instance; + +import net.minestom.server.coordinate.CoordConversion; +import net.minestom.server.instance.Chunk; +import org.jetbrains.annotations.ApiStatus; +import org.jetbrains.annotations.Nullable; +import org.jetbrains.annotations.UnmodifiableView; +import space.vectrix.flare.fastutil.Long2ObjectSyncMap; + +import java.util.Collection; +import java.util.Collections; +import java.util.List; +import java.util.Map; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.ConcurrentHashMap; +import java.util.concurrent.atomic.AtomicBoolean; +import java.util.concurrent.atomic.AtomicReference; +import java.util.function.Consumer; + +/** + * The {@link ChunkRegistry} class knows which chunk sits at which position and which position is + * busy, and it is the only place where either of those two answers changes. + *

+ * It was carved out of {@link FalcoInstance}, where the two maps and the four transitions between + * them were fields and {@code private} methods of a class of 1 722 lines. Nothing about the + * transitions changed in the move, and that is deliberate: the shape of the + * {@link ConcurrentHashMap#compute} calls below is what + * {@code FalcoInstanceLoadRaceTest#testConcurrentLoadsAndUnloadsNeverLeaveAChunkWhichCannotBeUnloaded} + * exists to protect, and a refactoring that improved them would be a rewrite of the one part of this + * module that was hardest to get right. + *

+ * + *

Why the map of running loads is the lock of a position

+ *

+ * Every transition of a position — starting a load, publishing its result, unloading the chunk + * again — happens inside a {@code compute} on the index of that position. That serialises them + * without putting a monitor over the whole instance, which is what {@code InstanceContainer} does and + * what NFR-006 forbids. Read that as the promise it is: no monitor spans the instance, not "nothing + * here ever takes a monitor". The chunk map takes one of its own on a miss, and the field says where + * and for how long. It is worth far more than the future it holds: without it an unload and the + * load it races can both believe they went first, and the chunk which loses ends up in the instance + * with its loaded flag already cleared, where nothing will ever unload it again. + *

+ *

+ * The steps a caller hands to {@link #publish} and {@link #remove} run inside that lock, and + * that is the whole reason they are parameters rather than something the caller does afterwards. + * Creating and deleting a tick partition has to be part of the same atomic step as entering and + * leaving the chunk map; splitting them is what lets Minestom delete a partition that is created a + * moment later, which leaves a chunk being ticked for the rest of the life of the server even though + * nothing else knows about it any more. + *

+ * + *

What a step handed to publish or remove may do

+ *

+ * Both steps run as the remapping function of a {@link ConcurrentHashMap#compute} on the map of + * running loads, so they inherit the rules of that method rather than merely being called at an + * awkward moment. A step has to be short, must not block, and must not reach back into this + * registry — not for its own position and not for another one. {@code compute} states outright that + * a remapping function must not attempt to update any other mapping of the same map, so a step which + * calls {@link #acquire}, {@link #publish}, {@link #remove}, {@link #release} or {@link #discard} + * can wedge a position for the rest of the life of the server. Reading which chunk sits somewhere is + * a read of the other map and is safe. + *

+ *

+ * A step must not throw either. {@code compute} rethrows and leaves its own mapping alone, but the + * chunk map was already written by the time the step runs, so what a throw leaves behind is a + * position on which the two maps disagree; {@link #publish} and {@link #remove} each name the state + * their own failure produces. This registry does not undo it and cannot: a step which failed half + * way holds bookkeeping only its caller knows about. + *

+ *

+ * What this does not say is "no foreign code inside the lock". {@link ChunkLifecycle} hands + * the removal step the very hook a caller installs through + * {@link FalcoInstance#setChunkLifecycle(Consumer, Consumer)}, because clearing the loaded flag of a + * chunk has to be atomic with that chunk leaving the chunk map — a chunk which is out of the map and + * still reports {@code isLoaded()} is one every {@code ChunkUtils#isLoaded} check in Minestom + * believes in. The rule is that whatever runs in there obeys the three constraints above. Everything + * which cannot — the events, the packets, the loader, the listeners — stays outside and is the + * caller's business. + *

+ * + *

Why this registry speaks {@link Chunk} and not {@link FalcoChunk}

+ *

+ * It holds no opinion about the chunk type, and it must not: since + * {@link FalcoInstance#setChunkLifecycle(Consumer, Consumer)} exists, a caller which owns another + * chunk type — a lighting chunk from {@code falco-light}, say — hands over the two {@code protected} + * hooks and its chunks are managed by this instance without ever being a {@link FalcoChunk}. + * Narrowing the two transitions to {@link FalcoChunk} would turn that supported case into a + * {@link ClassCastException} on the load path. + *

+ *

+ * This type is experimental. The instance module is new and its API may still change. + *

+ * + * @author TheMeinerLP + * @version 1.2.0 + * @since 0.4.0 + */ +@ApiStatus.Experimental +public final class ChunkRegistry { + + /** + * The loaded chunks, keyed by the chunk index of their position. + *

+ * A primitive keyed map rather than a {@code ConcurrentHashMap}, which boxed its key + * on every lookup — counted by {@code ChunkLookupAllocationTest}, which measures a position whose + * index is outside the autobox cache and finds nothing left afterwards. This is not offered as a + * speed change and no figure of this repository claims one: {@code getChunk} is reached on a chunk + * change rather than per block, because {@code ChunkCache} memoises in between, so the allocation + * is established and its cost is not. + *

+ *

+ * {@code Long2ObjectSyncMap} is a read map plus a dirty map in the shape of Go's {@code sync.Map}, + * not the copy-on-write map underneath {@code InstanceContainer}. It is in fact the very map + * {@code InstanceContainer#chunks} is — {@code Long2ObjectSyncMap.hashmap()} — so this field + * removed a difference between the two implementations rather than introducing one. A write after + * a run of misses rebuilds the dirty map, which is linear and lands on the load and unload path, + * where a tick partition is created and an event is dispatched anyway. + * {@code ChunkLookupBenchmark} prices the hit path and the write path against the boxed map. It + * does not price the miss path described next, and nothing in this repository does. + *

+ * + *

A lookup is not unconditionally lock free

+ *

+ * A lookup which finds its key in the read map takes no lock. A lookup which does not, while the + * map is amended, takes one: {@code Long2ObjectSyncMapImpl#getEntry} enters + * {@code synchronized(lock)} and consults the dirty map (flare-fastutil 2.0.1, + * {@code Long2ObjectSyncMapImpl.java:137-151}). The map is amended from the first {@code put} of a + * key the read map does not hold until a promotion clears the flag, and promotion needs as many + * misses as the dirty map has entries, so after n freshly loaded chunks the monitor sits on the + * miss path for up to n misses. The miss path is taken for a key that is absent altogether, not + * only for one sitting in the dirty map, which makes {@link #chunk(int, int)} returning null — the + * shape of every {@code ChunkUtils#isLoaded} style probe and of {@code FalcoInstance#getChunk} for + * an unloaded position — exactly the call that takes it. + *

+ *

+ * That does not contradict what this class says above about not putting a monitor over the whole + * instance: this monitor belongs to this map and guards only it, where the monitor of + * {@code InstanceContainer} is the instance and is held across placement rules, handlers, packets + * and events. What is withdrawn is the stronger claim that reads never block, because they can. + * No figure of this repository prices that path either way, which is why it is named here instead + * of argued away. + *

+ *

+ * Two further costs of that map are paid by this class and named here rather than discovered + * later. {@link #size()} and {@link #idle()} do not read a counter: both call the library's + * {@code promote()} first, which takes that same monitor and swaps the read map whenever the map + * is amended, and then walk the read map — so they are linear and on the lock, not merely + * linear. Neither is reached from a tick; they are reached from {@code FalcoInstance#unregister} + * and from a log line. And {@link #chunks()} builds a fresh view object per call, because the + * fastutil base class behind this map does not cache one the way {@code ConcurrentHashMap} does — + * the wrapper that method returns was allocated per call before this change too. + *

+ */ + private final Long2ObjectSyncMap chunks = Long2ObjectSyncMap.hashmap(); + + /** + * The chunks which are being loaded right now, keyed by chunk index, and the lock of a position. + *

+ * Holding the future rather than a flag is what makes two concurrent requests for the same chunk + * share one load instead of racing into two chunk objects. + *

+ */ + private final Map> loadingChunks = new ConcurrentHashMap<>(); + + /** + * Creates a registry which holds neither a chunk nor a running load. + *

+ * Written out rather than left to the compiler because this type is published: a default + * constructor carries no documentation, and the Javadoc build of this module treats a public + * type with one as an error. + *

+ */ + public ChunkRegistry() { + } + + /** + * What a caller asking for a position is told. + *

+ * A sealed hierarchy rather than a nullable future plus an out parameter, because the three + * answers are genuinely different and the caller has to handle all three: the chunk is already + * there, somebody else is loading it, or this caller now owns the load. The + * {@code AtomicReference} the previous shape needed to smuggle the first case out of a + * {@code compute} is what this replaces. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ + @ApiStatus.Experimental + public sealed interface LoadSlot { + + /** + * The position already carries a chunk and no load is needed. + * + * @param chunk the chunk at the position + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ + @ApiStatus.Experimental + record Loaded(Chunk chunk) implements LoadSlot { + } + + /** + * Somebody else is loading this position and the caller has to wait for their future. + * + * @param future the future of the running load + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ + @ApiStatus.Experimental + record Running(CompletableFuture future) implements LoadSlot { + } + + /** + * The caller now owns the load of this position and has to complete the future it handed in. + * + * @param future the future the caller handed in + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ + @ApiStatus.Experimental + record Claimed(CompletableFuture future) implements LoadSlot { + } + } + + /** + * Returns the chunk at a position. + * + * @param index the chunk index of the position + * @return the chunk, or null if the position carries none + */ + public @Nullable Chunk chunk(long index) { + return this.chunks.get(index); + } + + /** + * Returns the chunk at a position. + * + * @param chunkX the chunk X + * @param chunkZ the chunk Z + * @return the chunk, or null if the position carries none + */ + public @Nullable Chunk chunk(int chunkX, int chunkZ) { + return this.chunks.get(CoordConversion.chunkIndex(chunkX, chunkZ)); + } + + /** + * Returns a live, unmodifiable view of every chunk in this registry. + * + * @return the chunks of this registry + */ + public @UnmodifiableView Collection chunks() { + return Collections.unmodifiableCollection(this.chunks.values()); + } + + /** + * Returns a snapshot of every chunk in this registry, safe to iterate while it changes. + * + * @return the chunks of this registry at the moment of the call + */ + public List snapshot() { + return List.copyOf(this.chunks.values()); + } + + /** + * Returns a snapshot of every position which is being loaded right now. + * + * @return the positions with a running load at the moment of the call + */ + public List loadingPositions() { + return List.copyOf(this.loadingChunks.keySet()); + } + + /** + * Returns how many chunks this registry holds. + * + * @return the amount of loaded chunks + */ + public int size() { + return this.chunks.size(); + } + + /** + * Returns how many loads are running. + * + * @return the amount of running loads + */ + public int loading() { + return this.loadingChunks.size(); + } + + /** + * Reports whether this registry holds neither a chunk nor a running load. + * + * @return true if nothing is left in this registry + */ + public boolean idle() { + return this.chunks.isEmpty() && this.loadingChunks.isEmpty(); + } + + /** + * Decides who loads a position. + *

+ * The chunk map is read a second time inside the decision. Without that second read a caller + * which looked at the chunk map just before a load published, and reached this point just after + * that load removed its entry, would start a second load for a position which already has a + * chunk. The second chunk then replaces the first one in the map and the first one is orphaned: + * still marked as loaded, still holding its tick partition and its viewers, and no longer + * reachable. + *

+ * + * @param index the chunk index of the position + * @param own the future the caller offers to complete if it wins the slot + * @return which of the three cases the caller is in + */ + public LoadSlot acquire(long index, CompletableFuture own) { + final AtomicReference published = new AtomicReference<>(); + final CompletableFuture slot = this.loadingChunks.compute(index, (key, running) -> { + if (running != null) return running; + final Chunk cached = this.chunks.get(index); + if (cached != null) { + published.set(cached); + return null; + } + return own; + }); + final Chunk cached = published.get(); + + if (cached != null) return new LoadSlot.Loaded(cached); + if (slot != own) return new LoadSlot.Running(slot); + return new LoadSlot.Claimed(own); + } + + /** + * Gives up a slot without publishing anything, for a load which failed. + * + * @param index the chunk index of the position + * @param own the future of the load which is giving up + */ + public void release(long index, CompletableFuture own) { + this.loadingChunks.remove(index, own); + } + + /** + * Takes the slot of a running load so its chunk never reaches this registry. + *

+ * Removing the entry is the whole claim: a load publishes only while its own future is still the + * entry of the position, so a load which finds the slot empty or taken knows that somebody + * decided its result is no longer wanted. + *

+ * + * @param index the chunk index of the position + * @return the future of the claimed load, or null if there was none + */ + public @Nullable CompletableFuture discard(long index) { + final AtomicReference> claimed = new AtomicReference<>(); + + this.loadingChunks.compute(index, (key, running) -> { + claimed.set(running); + return null; + }); + return claimed.get(); + } + + /** + * Makes a chunk the chunk of its position, unless somebody claimed the load. + *

+ * The chunk enters the chunk map before the step runs, so the step already meets a registry which + * answers {@link #chunk(long)} with it. That order is what makes a throwing step expensive: the + * chunk stays in the chunk map, {@code compute} rethrows, and the entry of the running load + * survives untouched. The position is then loaded and loading at once, and every later + * {@link #acquire} on it hands out a {@link LoadSlot.Running} carrying a future nobody is going + * to complete any more. The constraints named on this class apply in full. + *

+ * + * @param index the chunk index of the position + * @param chunk the chunk to publish + * @param future the future of this load, which has to still be the entry of the position + * @param insideLock the step to run while the position is held, once, only if the publish + * happens; short, non-blocking, no call back into this registry, no exception + * @return true if the chunk is now the chunk of its position, false if the load was claimed + */ + public boolean publish(long index, Chunk chunk, CompletableFuture future, + Consumer insideLock) { + final AtomicBoolean published = new AtomicBoolean(); + + this.loadingChunks.compute(index, (key, running) -> { + if (running != future) return running; + this.chunks.put(index, chunk); + insideLock.accept(chunk); + published.set(true); + return null; + }); + return published.get(); + } + + /** + * Takes a chunk out of its position. + *

+ * The chunk leaves the chunk map before the step runs, and the entry of the position in the map + * of running loads is handed back unchanged — a position which carries a chunk has no running + * load, because {@link #acquire} claims a slot only for a position without one. A throwing step + * therefore leaves the removal standing while {@code compute} rethrows into the caller, which + * then never reaches the half of the unload that belongs outside the lock: the chunk is gone from + * this registry and only half unloaded. The constraints named on this class apply in full. + *

+ * + * @param index the chunk index of the position + * @param chunk the chunk to remove, which has to be the one at that position + * @param insideLock the step to run while the position is held, once, only if the removal + * happens; short, non-blocking, no call back into this registry, no exception + * @return true if the chunk was removed, false if it was not the chunk of that position + */ + public boolean remove(long index, Chunk chunk, Consumer insideLock) { + final AtomicBoolean removed = new AtomicBoolean(); + + this.loadingChunks.compute(index, (key, running) -> { + if (this.chunks.remove(index, chunk)) { + insideLock.accept(chunk); + removed.set(true); + } + return running; + }); + return removed.get(); + } +} diff --git a/falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoChunk.java b/falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoChunk.java index 2b1d9c8..ac33dca 100644 --- a/falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoChunk.java +++ b/falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoChunk.java @@ -1,12 +1,47 @@ package net.onelitefeather.falco.instance; +import it.unimi.dsi.fastutil.ints.Int2ObjectOpenHashMap; +import net.kyori.adventure.nbt.CompoundBinaryTag; +import net.kyori.adventure.nbt.LongArrayBinaryTag; +import net.minestom.server.MinecraftServer; +import net.minestom.server.coordinate.CoordConversion; +import net.minestom.server.coordinate.Point; +import net.minestom.server.entity.Entity; import net.minestom.server.instance.Chunk; -import net.minestom.server.instance.DynamicChunk; +import net.minestom.server.instance.EntityTracker; import net.minestom.server.instance.Instance; import net.minestom.server.instance.Section; +import net.minestom.server.instance.block.Block; +import net.minestom.server.instance.block.BlockHandler; +import net.minestom.server.instance.heightmap.Heightmap; +import net.minestom.server.instance.heightmap.MotionBlockingHeightmap; +import net.minestom.server.instance.heightmap.WorldSurfaceHeightmap; +import net.minestom.server.network.NetworkBuffer; +import net.minestom.server.network.packet.server.CachedPacket; +import net.minestom.server.network.packet.server.SendablePacket; +import net.minestom.server.network.packet.server.play.ChunkDataPacket; +import net.minestom.server.network.packet.server.play.data.ChunkData; +import net.minestom.server.network.packet.server.play.data.LightData; +import net.minestom.server.registry.RegistryKey; +import net.minestom.server.snapshot.ChunkSnapshot; +import net.minestom.server.snapshot.SnapshotImpl; +import net.minestom.server.snapshot.SnapshotUpdater; +import net.minestom.server.utils.ArrayUtils; +import net.minestom.server.world.DimensionType; +import net.minestom.server.world.biome.Biome; import org.jetbrains.annotations.ApiStatus; +import org.jetbrains.annotations.Contract; +import org.jetbrains.annotations.Nullable; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import java.util.ArrayList; +import java.util.BitSet; import java.util.List; +import java.util.Map; +import java.util.Objects; + +import static net.minestom.server.coordinate.CoordConversion.globalToSectionRelative; /** * The {@link FalcoChunk} class is the chunk of {@link FalcoInstance}. @@ -24,70 +59,403 @@ * hide the coupling instead of naming it. *

*

- * A third member has the same problem and needs no work here: the block setter which carries a - * placement and a destruction is {@code protected} on {@code Chunk} and only widened to public by - * {@link DynamicChunk}. Extending {@link DynamicChunk} rather than {@code Chunk} therefore also - * settles that one, which is a second reason for the choice of superclass. + * A third member has the same problem and is settled here as well: the block setter which carries a + * placement and a destruction is {@code protected} on {@code Chunk}. This class widens it to public, + * which is what lets {@link FalcoInstance} drive a placement from its own package. + *

+ * + *

Why the storage is a field and not a superclass

+ *

+ * This chunk used to extend {@code DynamicChunk} and inherit its sections. That inheritance is what + * this class gave up, because it cost more than it saved: {@code FalcoChunk} and + * {@code FalcoLightingChunk} both extended {@code DynamicChunk}, and a class has one superclass, so + * the two could never be combined. A server that wanted the instance of Falco and the light engine + * of Falco at the same time had to pick one. The blocks now sit behind {@link BlockStorage}, which + * is a field, and a field can be combined with anything. + *

+ *

+ * The second reason is that a memory layout is exactly the kind of decision that should be + * replaceable. As long as the sections were a {@code protected final} field of a Minestom class, a + * different layout meant a different chunk class and therefore a different everything — viewers, + * heightmaps, packet cache and lifecycle included. Behind the interface, a layout is a constructor + * argument. *

*

- * Everything else is inherited from {@link DynamicChunk}. This type deliberately adds no storage, - * no light handling and no packet handling of its own, because the block storage of Minestom is not - * the part of the instance which needed replacing. + * Everything that is not about where a block physically sits was carried over from + * {@code DynamicChunk} as it stands: the entries map, the two heightmaps, the cached chunk packet + * and the viewer and tag plumbing inherited from {@code Chunk}. Copying it is deliberate. This class + * is measured against {@code DynamicChunk}, and a difference that came from rewriting the + * bookkeeping would be indistinguishable from a difference that came from the storage. *

*

- * Like its superclass, this chunk is not thread-safe on its own. Callers hold the chunk lock, which - * {@link Chunk#lockWriteLock()} and {@link Chunk#lockReadLock()} provide. + * The second block map is the one post that was not carried over at all. {@code DynamicChunk} keeps + * a subset of its entries in a map of its own so that a tick can leave early; {@link #tickableCount} + * buys the same early exit without the map — see there for what that trade costs. What a tick does + * is unchanged, which {@code FalcoChunkTest} pins from both directions. + *

+ *

+ * The heightmaps are the one place where the copying stops at the {@code when} rather than the + * {@code what}. They are built on the first question instead of in a field initialiser — see + * {@link #motionBlockingHeightmap()}, which carries the bytes and the conditions they were measured + * under. In a fresh {@code DynamicChunk} the two of them are the second largest post after the + * sections; in a fresh chunk of this class, whose sections are shared and empty until something + * writes, they were the largest post there was, which is why they and not the sections are what this + * class defers. What they contain, and the order in which {@link #setBlock} refreshes them, is + * unchanged, which is what keeps the comparison against {@code DynamicChunk} honest. + *

+ * + *

Where the coordinates are folded

+ *

+ * {@code Instance#setBlock} hands a chunk the coordinates of the world, not of the chunk: an + * {@code x} of {@code -3} is a legitimate argument here and means the fourteenth column of the chunk + * at {@code chunkX == -1}. {@code DynamicChunk} folds them itself, at every use. This class folds + * them once, on this side of the seam, and passes chunk-local {@code x} and {@code z} to + * {@link BlockStorage}, which is what that interface documents. + *

+ *

+ * The alternative — handing the storage what the instance handed the chunk — would work for + * {@link SectionBlockStorage}, which folds again internally, and would quietly break any + * implementation that indexes an array by {@code x}. A storage cannot fold on its own without + * knowing which chunk it belongs to, and giving it that knowledge would put the chunk position into + * the one part of the design that was built not to need it. The height stays absolute, because a + * storage does know its own vertical extent. + *

+ *

+ * Like {@code DynamicChunk}, this chunk is not thread-safe on its own. Callers hold the chunk lock, + * which {@link Chunk#lockWriteLock()} and {@link Chunk#lockReadLock()} provide. + *

+ * + *

Which of its own sections this chunk is allowed to create

+ *

+ * None, on any path of its own. The packet it sends, the light data it collects, the snapshot it + * takes and the scan that starts a heightmap refresh all read through {@link BlockStorage#views()} + * and {@link BlockStorage#view(int)}, which hand out whatever the storage currently holds and create + * nothing. Only {@link #getSections()} and {@link #getSection(int)} materialise, because those two + * are what Minestom calls when it is about to write into a section — the generator of an + * {@code InstanceContainer}, a chunk loader, the light engine — and a storage cannot tell a reader + * from a writer through them. + *

+ *

+ * The one place where that boundary is crossed against this chunk's will is the heightmap. + * {@code Heightmap#refresh(int, int, int)} reaches its sections through {@code Chunk#getSection(int)} + * and cannot be overridden, because it ends in a {@code private} setter over a {@code private} + * array. A refresh therefore materialises every empty section it walks through below the highest + * non-empty one. In a generated overworld that is none; the height profile of the census puts the + * empty share below world height sixty-four at {@code 0,0 %}. In a world of floating islands it is + * not none, and {@code SectionMaterialisationTest} states the number rather than leaving it to the + * imagination. *

*

* This type is experimental. The instance module is new and its API may still change. *

* + * + *

How something else takes part in the life of this chunk

+ *

+ * Through {@link #addLifecycleListener(ChunkLifecycleListener)}, and that is US-3.03. Everything + * this class does that another part of a server may want to know about — being published, finishing + * a load, being ticked, receiving a block, leaving its instance — used to be reachable only by + * overriding it, which meant being the superclass of this chunk, of which there can be exactly one. + * A listener is a field, so two of them fit where one subclass did. + *

+ *

+ * Four of the five transitions are reported from where they happen and the fifth, the publish, from + * {@link #notifyPublished()}, because nothing on a chunk marks it. The load and the unload report + * from the {@code protected} hooks {@link #onLoad()} and {@link #unload()} rather than from the + * public {@link #markLoaded()} and {@link #markUnloaded()} that widen them: a chunk of this type is + * driven by {@link FalcoInstance} through the public pair and by an {@code InstanceContainer} + * through the hooks, and a report on the wrong one of the two would be silent for half the callers. + *

+ * * @author TheMeinerLP - * @version 1.0.0 + * @version 3.8.0 * @since 0.1.0 */ @ApiStatus.Experimental -public class FalcoChunk extends DynamicChunk { +public class FalcoChunk extends Chunk { + + private static final Logger LOGGER = LoggerFactory.getLogger(FalcoChunk.class); + + private final BlockStorage storage; + + /** + * The blocks which are worth keeping as objects, keyed by {@code CoordConversion#chunkBlockIndex}. + *

+ * A palette holds a state id and nothing else, so a block with a handler, with NBT or with a + * block entity would lose that part of itself on the way in. These are the ones that are kept + * whole, and {@link #getBlock(int, int, int, Condition)} looks here before it asks the storage. + *

+ *

+ * Private, where {@code DynamicChunk} has it {@code protected}. That modifier was inherited along + * with everything else this class copied while it still extended {@code DynamicChunk}, and + * narrowing it costs nothing even now that a subclass exists: {@code FalcoLightingChunk} carries + * a packet cache and needs no block object, and the seam a subclass is meant to use is + * {@link BlockStorage}, which is a constructor argument rather than a field to reach into. + *

+ *

+ * What {@code protected} would still cost is real. {@code final} on a map protects the reference + * and nothing behind it, so a visible field hands anyone who subclasses this chunk — from any + * package, since the class has to stay open for {@code FalcoLightingChunk} — a writable map that + * the write lock does not cover and that {@link #tickableCount} is counted against. A foreign + * {@code entries.remove} would leave the counter above zero with nothing left to tick, which is + * exactly the drift the counter was introduced to make impossible. A subclass that needs the + * block objects asks {@link #getBlock(int, int, int, Condition)} with {@link Condition#CACHED}, + * which answers the same question without handing out the map. + *

+ */ + private final Int2ObjectOpenHashMap entries = new Int2ObjectOpenHashMap<>(0); + + /** + * How many of {@link #entries} carry a handler which asked to be ticked. + *

+ * This is what is left of the second map {@code DynamicChunk} keeps. That map held a subset of + * {@link #entries} under the same keys pointing at the same blocks, so it was a second copy of + * information the chunk already had, at the price of one {@code Int2ObjectOpenHashMap} and its two + * backing arrays per chunk — for every chunk in a world, whether or not it holds a single block + * entity. + *

+ *

+ * What that map bought was the early exit of {@link #tick(long)}: almost every chunk has nothing + * to tick, and a tick which had to walk the entries to find that out would make the cost of + * ticking depend on how many block entities a chunk happens to hold. The counter buys the same + * exit for four bytes. What is genuinely paid is the case that remains — a chunk which holds both + * tickable and non-tickable block entities now walks all of them once per tick instead of only the + * tickable ones. + *

+ *

+ * Volatile because the one read that matters happens without the chunk lock. Every write is under + * the write lock — {@link #setBlock} and {@link #reset} both open with {@code assertWriteLock()}, + * and {@link #copy} writes only into a chunk it just created — so the writers are serialised and + * the non-atomic {@code +=} below cannot lose an update. The reader is the other side: + * {@link #tick(long)} takes no lock at all, and it cannot, because Minestom calls it from a + * {@code TickThread} that holds its own {@code ReentrantLock} and never the + * {@link Chunk#lockReadLock() read lock} of the chunk — {@code Chunk#tick} says as much in its own + * Javadoc, that it "doesn't necessary have to be thread-safe". A chunk is written from wherever a + * placement, a generator or a loader happens to run, so writer and ticker are routinely different + * threads with no happens-before between them. + *

+ *

+ * Without the modifier the tick thread may keep reading a cached zero after a block entity was + * placed, and a chunk that silently stops ticking is the kind of defect that surfaces as a + * complaint about furnaces months later rather than as a failing test. Four bytes were already the + * price of this field; the barrier is paid on a read that a chunk performs once per tick and on + * writes that already stop to take a lock. + *

+ */ + private volatile int tickableCount; + + private volatile boolean needsCompleteHeightmapRefresh = true; + + /** + * The highest block per column which stops movement, built when something first asks for it. + *

+ * Volatile because the creation below is a double-checked lock, and a non-volatile field would + * let a second thread see a partly constructed {@code MotionBlockingHeightmap} — which carries a + * {@code short[256]} of its own that would then be read before it exists. + *

+ */ + private volatile Heightmap motionBlocking; + + /** + * The highest block per column which is not air, built when something first asks for it. + */ + private volatile Heightmap worldSurface; + + /** + * The serialised chunk, kept until something invalidates it. + *

+ * A chunk is sent to every player who walks into view of it, and serialising a full chunk is far + * more expensive than the write which changed it. The cache turns that into one serialisation per + * change instead of one per viewer. + *

+ */ + private final CachedPacket chunkCache = new CachedPacket(this::createChunkPacket); /** - * Creates an empty chunk at the given position. + * What is told about the transitions of this chunk, null while nobody listens. + *

+ * One reference and not a list. A list is an object per chunk and an iterator per transition, and + * a fresh chunk of this class retains 840 bytes in total — a per-chunk collection for a feature + * almost no chunk uses would give back a quarter of what stage 2 bought. More than one listener + * composes through {@link ChunkLifecycleListener#of}, which allocates once, at registration. + *

+ *

+ * Volatile because a listener may be installed by the thread that loads a chunk and read by the + * thread that ticks it. + *

+ */ + private volatile @Nullable ChunkLifecycleListener lifecycleListener; + + /** + * Creates an empty chunk at the given position, storing its blocks in sections which are + * allocated only once something is written into them. + *

+ * {@link LazySectionBlockStorage} is the default rather than {@link SectionBlockStorage} because + * an empty chunk is the state every chunk starts in and the state most sections of a finished + * chunk stay in; a caller who wants a section per slot regardless still gets one by passing + * {@link SectionBlockStorage} to {@link #FalcoChunk(Instance, int, int, BlockStorage)}. + *

* * @param instance the instance which owns the chunk * @param chunkX the chunk X * @param chunkZ the chunk Z */ public FalcoChunk(Instance instance, int chunkX, int chunkZ) { - super(instance, chunkX, chunkZ); + super(instance, chunkX, chunkZ, true); + // Must be built here and not in a field initialiser: the super constructor is what computes + // minSection and maxSection, and the storage is sized from them. + this.storage = new LazySectionBlockStorage(minSection, maxSection - minSection); } /** - * Creates a chunk which takes over the given sections. + * Creates a chunk which takes over the given storage. *

- * Used by {@link #copy(Instance, int, int)}; the sections are not cloned here, so a caller has - * to hand over sections nobody else writes to. + * This is the constructor that makes the layout a choice of the caller. It is also what + * {@link #copy(Instance, int, int)} uses, with a storage that copied itself; the storage is not + * copied here, so a caller has to hand over one that nobody else writes to. *

* * @param instance the instance which owns the chunk * @param chunkX the chunk X * @param chunkZ the chunk Z - * @param sections the sections of the chunk, from the bottom one upwards + * @param storage the storage which holds the blocks and biomes of the chunk + * @since 0.4.0 + */ + public FalcoChunk(Instance instance, int chunkX, int chunkZ, BlockStorage storage) { + super(instance, chunkX, chunkZ, true); + this.storage = storage; + } + + /** + * Hands out the storage which holds the blocks of this chunk. + *

+ * Exposed because the storage is the part a caller may want to inspect or measure without going + * through the chunk, and because the choice of layout is otherwise invisible from the outside. + *

+ * + * @return the storage of this chunk + * @since 0.4.0 + */ + public BlockStorage storage() { + return this.storage; + } + + /** + * Checks that a chunk can be written to through the instance module, and types it. + *

+ * The block setter that carries a placement and a destruction is {@code protected} on + * {@code Chunk} and only widened to public by {@link FalcoChunk} and {@code DynamicChunk}. A chunk + * of any other type is therefore accepted everywhere else in this module — a caller which owns its + * own chunk type hands the two lifecycle hooks over through + * {@link FalcoInstance#setChunkLifecycle(java.util.function.Consumer, java.util.function.Consumer)} + * and takes part in the lifecycle without ever being a {@link FalcoChunk} — and refused here, on + * the one path this module cannot reach without the subclass it ships itself. + *

+ *

+ * It lives on the chunk rather than on the instance because the check belongs to the type it + * checks for, and because {@link BlockWriter} is its second caller; a check that two parts copy is + * a check that can drift. + *

+ * + * @param chunk the chunk to check + * @return the same chunk, typed + * @throws FalcoInstanceException if the chunk is not a {@link FalcoChunk} + * @since 0.4.0 */ - protected FalcoChunk(Instance instance, int chunkX, int chunkZ, List
sections) { - super(instance, chunkX, chunkZ, sections); + @Contract("_ -> param1") + public static FalcoChunk require(Chunk chunk) { + if (chunk instanceof FalcoChunk falcoChunk) return falcoChunk; + throw new FalcoInstanceException("the instance module writes blocks through " + + FalcoChunk.class.getName() + ", whose block setter carrying a placement is public," + + " but its chunk supplier produced a " + chunk.getClass().getName()); + } + + /** + * Adds a listener to this chunk. + *

+ * A second listener is composed with the first through {@link ChunkLifecycleListener#of} rather + * than appended to a collection, which is where the reason for that lives. + *

+ *

+ * Registration itself is not atomic: this reads the field and writes it back, so two threads + * registering at the same moment can lose one of the two. That is deliberate and it is what the + * field being a plain volatile reference costs. A listener is installed while a chunk is being + * built — {@link ChunkLifecycle#create(int, int)} does it before the generator runs — and paying + * for a compare-and-set on every chunk of a world to make a setup-time call thread-safe would + * charge the case that happens millions of times for the case that happens once. + *

+ * + * @param listener the listener to add + * @throws NullPointerException if the listener is null + * @since 0.4.0 + */ + public void addLifecycleListener(ChunkLifecycleListener listener) { + final ChunkLifecycleListener current = this.lifecycleListener; + this.lifecycleListener = current == null ? Objects.requireNonNull(listener, + "the listener cannot be null") : ChunkLifecycleListener.of(current, listener); + } + + /** + * Hands out what is told about the transitions of this chunk. + * + * @return the listener of this chunk, or null if nothing listens + * @since 0.4.0 + */ + public @Nullable ChunkLifecycleListener lifecycleListener() { + return this.lifecycleListener; + } + + /** + * Tells the chunk that it has become part of its instance. + *

+ * Separate from {@link #markLoaded()} because publishing and finishing a load are two different + * moments: a chunk is in the registry and has a tick partition before its loaded flag is set, and + * a listener that wants to see the world exactly as the instance does needs the first, not the + * second. + *

+ * + * @since 0.4.0 + */ + public void notifyPublished() { + final ChunkLifecycleListener listener = this.lifecycleListener; + if (listener != null) listener.onPublish(new ChunkLifecycleEvent(this, 0L)); } /** * Tells the chunk that it has finished loading. *

* This is the reachable form of the {@code protected} {@code Chunk#onLoad()} hook. - * {@link FalcoInstance} calls it once, after the chunk has been put into the chunk map of the + * {@link ChunkLifecycle} calls it once, after the chunk has been put into the registry of the * instance and after its tick partition exists, which is the order Minestom uses as well. *

+ *

+ * It carries no notification of its own; the hook it widens does. See {@link #onLoad()} for why + * the two are that way round. + *

*/ public void markLoaded() { onLoad(); } + /** + * Reports the finished load to the listener of this chunk. + *

+ * The notification sits on the {@code protected} hook rather than on {@link #markLoaded()}, + * because this chunk is reached through two doors and only one of them is that method. + * {@link FalcoInstance} drives {@link #markLoaded()}, but an {@code InstanceContainer} calls this + * hook directly from {@code retrieveChunk} — it lives in the Minestom package and does not need + * the widening. A chunk in a container would otherwise report its tick and its block writes and + * stay silent about the one transition a light engine cannot do without, which is exactly the + * shape of defect Task 8 already found on the loader arm: two doors, one report. + *

+ */ + @Override + protected void onLoad() { + super.onLoad(); + final ChunkLifecycleListener listener = this.lifecycleListener; + if (listener != null) listener.onLoad(new ChunkLifecycleEvent(this, 0L)); + } + /** * Tells the chunk that it is no longer part of its instance. *

@@ -101,12 +469,398 @@ public void markUnloaded() { unload(); } + /** + * Reports the departure to the listener of this chunk, and clears the loaded flag. + *

+ * On the hook and not on {@link #markUnloaded()}, for the reason given on {@link #onLoad()}: an + * {@code InstanceContainer} calls this one directly. + *

+ */ + @Override + protected void unload() { + super.unload(); + final ChunkLifecycleListener listener = this.lifecycleListener; + if (listener != null) listener.onUnload(new ChunkLifecycleEvent(this, 0L)); + } + + /** + * Writes a block into this chunk and runs the bookkeeping that goes with it. + *

+ * Widened to public so {@link FalcoInstance}, which lives outside the Minestom package, can pass + * a placement and a destruction along. Everything but the one line that reaches the storage is + * the body {@code DynamicChunk} has, in its order: the cache is dropped first, then the block is + * written, then the entries and the tickable counter are brought in line with it, then the + * handlers of the old and the new block are told, and only then are the heightmaps refreshed. + *

+ *

+ * The order matters. A handler that reads the chunk during {@code onPlace} has to see the block + * that was just written, which is why the storage is written before the handlers run. + *

+ *

+ * The caller has to hold the write lock of this chunk. + *

+ * + * @param x the block X + * @param y the block Y + * @param z the block Z + * @param block the block to write + * @param placement the placement which caused the write, null if it was not a placement + * @param destroy the destruction which caused the write, null if it was not a break + */ + @Override + public void setBlock(int x, int y, int z, Block block, + @Nullable BlockHandler.Placement placement, + @Nullable BlockHandler.Destroy destroy) { + assertWriteLock(); + final DimensionType instanceDim = instance.getCachedDimensionType(); + if (y >= instanceDim.maxY() || y < instanceDim.minY()) { + LOGGER.warn("tried to set a block outside the world bounds, should be within [{}, {}): {}", + instanceDim.minY(), instanceDim.maxY(), y); + return; + } + + this.chunkCache.invalidate(); + + final int sectionRelativeX = globalToSectionRelative(x); + final int sectionRelativeZ = globalToSectionRelative(z); + + this.storage.setBlock(sectionRelativeX, y, sectionRelativeZ, block); + + final int index = CoordConversion.chunkBlockIndex(x, y, z); + // Handler + final BlockHandler handler = block.handler(); + final Block lastCachedBlock; + if (handler != null || block.hasNbt() || block.registry().isBlockEntity()) { + lastCachedBlock = this.entries.put(index, block); + } else { + lastCachedBlock = this.entries.remove(index); + } + // Block tick. A tickable block always carries a handler and is therefore always in the + // entries above, so the counter and the map can never disagree about who is in which. + final BlockHandler previousHandler = lastCachedBlock == null ? null : lastCachedBlock.handler(); + final boolean wasTickable = previousHandler != null && previousHandler.isTickable(); + final boolean isTickable = handler != null && handler.isTickable(); + if (wasTickable != isTickable) { + this.tickableCount += isTickable ? 1 : -1; + } + + // Update block handlers + if (lastCachedBlock != null && lastCachedBlock.handler() != null) { + // Previous destroy + lastCachedBlock.handler().onDestroy(Objects.requireNonNullElseGet(destroy, + () -> new BlockHandler.Destroy(lastCachedBlock, block, instance, + CoordConversion.chunkBlockRelativeGetGlobal(sectionRelativeX, y, sectionRelativeZ, chunkX, chunkZ)))); + } + if (handler != null) { + // New placement + final Point placePoint = CoordConversion.chunkBlockRelativeGetGlobal(sectionRelativeX, y, sectionRelativeZ, chunkX, chunkZ); + handler.onPlace(Objects.requireNonNullElseGet(placement, + () -> new BlockHandler.Placement(block, + Objects.requireNonNullElseGet(lastCachedBlock, () -> this.getBlock(placePoint, Condition.TYPE)), + instance, placePoint))); + } + + // UpdateHeightMaps + if (this.needsCompleteHeightmapRefresh) calculateFullHeightmap(); + motionBlockingHeightmap().refresh(sectionRelativeX, y, sectionRelativeZ, block); + worldSurfaceHeightmap().refresh(sectionRelativeX, y, sectionRelativeZ, block); + + // Last, so a listener reading this chunk sees the finished state rather than a chunk whose + // heightmaps still describe the block that was overwritten. + final ChunkLifecycleListener listener = this.lifecycleListener; + if (listener != null) listener.onBlockChange(this, x, y, z, block); + } + + /** + * Reads the block at a position. + *

+ * The entries map is consulted first, because it is the only place a handler or NBT survives; a + * caller which asked for {@link Condition#TYPE} skips that lookup, since a state id is all it + * wants. Only what the entries do not answer reaches the storage. + *

+ *

+ * A height outside the world is answered with air rather than with an exception, because the + * neighbour updates of a block write walk one block up and down and would otherwise fall off the + * world at its floor and its ceiling. Air is also what a stored state the block registry does not + * know reads back as, which {@link BlockStorage#getBlock(int, int, int, Condition)} guarantees — + * together the two are what lets this method promise a block for every height, which + * {@code Condition#NONE} requires of it. + *

+ *

+ * The caller has to hold the read lock of this chunk. + *

+ * + * @param x the block X + * @param y the block Y + * @param z the block Z + * @param condition what the caller is willing to accept + * @return the block, or null if the condition excludes it + */ + @Override + public @Nullable Block getBlock(int x, int y, int z, Condition condition) { + assertReadLock(); + if (y < minSection * CHUNK_SECTION_SIZE || y >= maxSection * CHUNK_SECTION_SIZE) + return Block.AIR; // Out of bounds + + // Verify if the block object is present + if (condition != Condition.TYPE) { + final Block entry = !this.entries.isEmpty() + ? this.entries.get(CoordConversion.chunkBlockIndex(x, y, z)) : null; + if (entry != null || condition == Condition.CACHED) { + return entry; + } + } + return this.storage.getBlock(globalToSectionRelative(x), y, globalToSectionRelative(z), condition); + } + + /** + * Writes a biome into this chunk. + *

+ * The cached packet has to be dropped here as well: a biome is part of the section data a client + * receives, so a chunk that kept its cache would keep sending the old biome. + *

+ *

+ * The caller has to hold the write lock of this chunk. + *

+ * + * @param x the block X + * @param y the block Y + * @param z the block Z + * @param biome the biome to write + */ + @Override + public void setBiome(int x, int y, int z, RegistryKey biome) { + assertWriteLock(); + this.chunkCache.invalidate(); + this.storage.setBiome(globalToSectionRelative(x), y, globalToSectionRelative(z), biome); + } + + /** + * Reads the biome at a position. + *

+ * The caller has to hold the read lock of this chunk. + *

+ * + * @param x the block X + * @param y the block Y + * @param z the block Z + * @return the biome + */ + @Override + public RegistryKey getBiome(int x, int y, int z) { + assertReadLock(); + return this.storage.getBiome(globalToSectionRelative(x), y, globalToSectionRelative(z)); + } + + /** + * Hands out the sections of this chunk, from the bottom one upwards. + * + * @return the sections of this chunk + */ + @Override + public List
getSections() { + return this.storage.sections(); + } + + /** + * Hands out one section of this chunk. + *

+ * {@code Chunk#getSection(int)} counts sections in world terms, which is negative below the zero + * line, while {@link BlockStorage#section(int)} counts from the bottom section of the chunk. + * Subtracting {@code minSection} is that translation, and it is the one place where forgetting it + * would be silent: a wrong section still holds blocks, just not the ones that were asked for. + *

+ * + *

+ * No lock is asserted here, and that is not an oversight of this class but a property of its + * callers: {@code Instance#getBlockLight}, {@code Instance#getSkyLight} and + * {@code Instance#invalidateSection} all reach this method holding no chunk lock, and + * {@code Heightmap#refresh(int)} reaches it holding the read lock, which + * {@link Chunk#lockWriteLock()} refuses to be taken on top of. Materialising is therefore made + * safe where it happens rather than here — see {@link LazySectionBlockStorage} for the step and + * for why it publishes a slot the way it does. + *

+ * + * @param section the section index in world terms + * @return the section + */ + @Override + public Section getSection(int section) { + return this.storage.section(section - minSection); + } + + /** + * Hands out the heightmap of the highest movement-blocking block per column, building it if this + * chunk does not have one yet. + *

+ * A heightmap is a {@code short[256]} plus its carrier: four objects and {@code 1 120} bytes for + * the two of them together. Which share of a chunk that is depends entirely on which chunk is + * being talked about, so both are named here. Against a fresh {@code DynamicChunk}, which retains + * {@code 6 848} bytes, it is {@code 16,4 %} — the second largest post after the sections. Against + * a fresh chunk of this class the comparison needs no percentage at all: a fresh + * {@code FalcoChunk} retains {@code 840} bytes in total, which is less than the two heightmaps + * alone would weigh. That is why they and not the sections are the post this class defers. + *

+ *

+ * The {@code 6 848} and the {@code 840} are what {@code ChunkFootprintTest} measures with jol + * 0.17 through the instrumentation agent on OpenJDK 25.0.3 with a twelve byte object header and an + * alignment of eight ({@code falco.compactHeaders=false}), over an overworld chunk of 24 sections, + * counting what the chunk retains once the instance is subtracted; the {@code 1 120} is the two + * heightmaps of that {@code DynamicChunk} in the same walk. Under compact headers, or at another + * world height, they are different numbers. + *

+ *

+ * Minestom builds both heightmaps in a field initialiser, so a chunk pays for them whether or not + * anybody ever reads a height. Most chunks do get asked eventually — + * a chunk that is sent to a client hands both of them to the packet, and a chunk that is written + * to refreshes both — but the window between construction and that first question is exactly the + * window a chunk loader and a generator work in, and a chunk that is loaded, read and never sent + * never leaves it. + *

+ *

+ * The creation is a double-checked lock over the monitor of this chunk rather than a plain lazy + * field. The read lock and the write lock of a chunk do not cover this method — a caller may reach + * it without either — and two threads which both created a heightmap would leave one of them + * holding heights that the chunk then throws away. + *

+ * + * @return the motion blocking heightmap + */ + @Override + public Heightmap motionBlockingHeightmap() { + Heightmap heightmap = this.motionBlocking; + + if (heightmap != null) return heightmap; + synchronized (this) { + heightmap = this.motionBlocking; + if (heightmap == null) { + heightmap = new MotionBlockingHeightmap(this); + this.motionBlocking = heightmap; + } + return heightmap; + } + } + + /** + * Hands out the heightmap of the highest non-air block per column, building it if this chunk does + * not have one yet. + * + * @return the world surface heightmap + */ + @Override + public Heightmap worldSurfaceHeightmap() { + Heightmap heightmap = this.worldSurface; + + if (heightmap != null) return heightmap; + synchronized (this) { + heightmap = this.worldSurface; + if (heightmap == null) { + heightmap = new WorldSurfaceHeightmap(this); + this.worldSurface = heightmap; + } + return heightmap; + } + } + + /** + * Reports whether this chunk has built its heightmaps yet. + *

+ * Exposed because a property nothing can observe is a property nothing can assert, and the whole + * value of building them on demand is the claim that a chunk which was only loaded holds none. + *

+ * + * @return whether either heightmap exists + * @since 0.4.0 + */ + public boolean hasHeightmaps() { + return this.motionBlocking != null || this.worldSurface != null; + } + + /** + * Takes over the heightmaps a chunk loader read from disk. + *

+ * A heightmap that is not in the tag is left alone rather than zeroed, because an absent + * heightmap means the file did not carry one, not that every column is empty. + *

+ *

+ * The caller has to hold the write lock of this chunk. + *

+ * + * @param heightmapsNBT the heightmap compound of the chunk + */ + @Override + public void loadHeightmapsFromNBT(CompoundBinaryTag heightmapsNBT) { + assertWriteLock(); + if (heightmapsNBT.get(motionBlockingHeightmap().type().name()) instanceof LongArrayBinaryTag array) { + motionBlockingHeightmap().loadFrom(array.value()); + } + + if (heightmapsNBT.get(worldSurfaceHeightmap().type().name()) instanceof LongArrayBinaryTag array) { + worldSurfaceHeightmap().loadFrom(array.value()); + } + } + + /** + * Ticks the block handlers of this chunk which asked to be ticked. + *

+ * The counter check up front is what keeps a world of ordinary chunks cheap: almost every chunk + * has no tickable block at all, and this makes its tick a single comparison. That property is the + * one {@link #tickableCount} exists to preserve now that the second map which used to provide it + * is gone; the walk below is over {@link #entries}, so a chunk which does hold tickable blocks + * pays for the block entities it holds beside them. + *

+ *

+ * The listener is told before that early exit and not after it. A listener which wants a + * heartbeat has to get one from every chunk, and almost every chunk has no tickable block at all, + * so a notification behind the counter check would reach exactly the chunks that need it least. + * The event is built only once the field has been found non-null, which is what keeps the + * unheard case at the single comparison it was — {@code ChunkLifecycleAllocationTest} measures + * both halves of that. + *

+ * + * @param time the time of the tick in milliseconds + */ + @Override + public void tick(long time) { + final ChunkLifecycleListener listener = this.lifecycleListener; + if (listener != null) listener.onTick(new ChunkLifecycleEvent(this, time)); + if (this.tickableCount == 0) return; + this.entries.int2ObjectEntrySet().fastForEach(entry -> { + final Block block = entry.getValue(); + final BlockHandler handler = block.handler(); + if (handler == null || !handler.isTickable()) return; + final Point blockPosition = CoordConversion.chunkBlockIndexGetGlobal(entry.getIntKey(), chunkX, chunkZ); + handler.tick(new BlockHandler.Tick(block, instance, blockPosition)); + }); + } + + /** + * Hands out the packet which carries this chunk to a client. + *

+ * The cache itself is returned, not a packet. It serialises on the first send after a change and + * every further viewer receives the bytes that were already there. + *

+ * + * @return the cached chunk packet + */ + @Override + public SendablePacket getFullDataPacket() { + return this.chunkCache; + } + /** * Creates a copy of this chunk at the given position. *

- * Overridden so the copy is a {@link FalcoChunk} again. The inherited implementation returns a - * plain {@link DynamicChunk}, and such a chunk could never be unloaded by - * {@link FalcoInstance} because its hooks are out of reach. + * The copy is a {@link FalcoChunk} again, which matters beyond tidiness: a plain + * {@code DynamicChunk} could never be unloaded by {@link FalcoInstance}, because its lifecycle + * hooks are out of reach from this package. + *

+ *

+ * The entries and the tickable counter are both carried over. {@code DynamicChunk#copy} carries + * only the entries and leaves its second map behind, which leaves a copied chunk with block + * entities that have stopped ticking; that omission is a defect this class already corrected + * before the storage moved, and it stays corrected — the counter is the same correction, in the + * form the second map left behind. *

*

* The caller has to hold the read lock of this chunk. @@ -120,10 +874,242 @@ public void markUnloaded() { @Override public Chunk copy(Instance instance, int chunkX, int chunkZ) { assertReadLock(); - final List

copiedSections = this.sections.stream().map(Section::clone).toList(); - final FalcoChunk copy = new FalcoChunk(instance, chunkX, chunkZ, copiedSections); + final FalcoChunk copy = new FalcoChunk(instance, chunkX, chunkZ, this.storage.copy()); + copy.entries.putAll(this.entries); - copy.tickableMap.putAll(this.tickableMap); + copy.tickableCount = this.tickableCount; return copy; } + + /** + * Empties this chunk. + *

+ * The counter goes back to zero with the entries it counts. {@code DynamicChunk#reset} clears its + * entries and leaves its second map behind, so a reset chunk there keeps ticking blocks it no + * longer holds; here the two cannot drift apart, because clearing one without the other would + * leave a chunk whose tick can never take its early exit again. + *

+ *

+ * The caller has to hold the write lock of this chunk. + *

+ */ + @Override + public void reset() { + assertWriteLock(); + this.storage.clear(); + this.entries.clear(); + this.tickableCount = 0; + } + + /** + * Drops everything this chunk derived from its blocks. + *

+ * Both the packet and the heightmaps are dropped, because the case this exists for is a change + * that did not go through {@link #setBlock(int, int, int, Block, BlockHandler.Placement, BlockHandler.Destroy)} + * — a generator or a loader writing into the sections directly — and such a change leaves no + * trace either of them would notice on their own. + *

+ */ + @Override + public void invalidate() { + this.needsCompleteHeightmapRefresh = true; + this.chunkCache.invalidate(); + } + + /** + * Takes a snapshot of this chunk. + *

+ * The sections are cloned rather than shared, because a snapshot is read without any lock and a + * shared section would keep changing underneath its reader. + *

+ * + * @param updater the updater which resolves the references of the snapshot + * @return the snapshot of this chunk + */ + @Override + public ChunkSnapshot updateSnapshot(SnapshotUpdater updater) { + final List
sections = this.storage.views(); + final Section[] clonedSections = new Section[sections.size()]; + for (int i = 0; i < clonedSections.length; i++) { + final Section section = sections.get(i); + // A shared section must not end up inside a snapshot even though it never changes: a + // snapshot is read without any lock and by callers this class does not know, and one that + // wrote into it would write into every empty section of the process. A fresh section is + // the same content and cannot be aliased. + clonedSections[i] = this.storage.shared(i) ? new Section() : section.clone(); + } + final var entities = instance.getEntityTracker().chunkEntities(chunkX, chunkZ, EntityTracker.Target.ENTITIES); + final int[] entityIds = ArrayUtils.mapToIntArray(entities, Entity::getEntityId); + return new SnapshotImpl.Chunk(minSection, chunkX, chunkZ, + clonedSections, this.entries.clone(), entityIds, updater.reference(instance), + tagHandler().readableCopy()); + } + + /** + * Serialises this chunk into the packet a client receives. + *

+ * The lock dance is the one {@code DynamicChunk} performs and it is not decoration. The heightmap + * refresh writes, so it needs the write lock; the light computation is left outside every lock, + * because it reaches into neighbouring chunks and taking their locks while holding this one is + * how two chunks deadlock each other; the section read only needs the read lock. + *

+ * + * @return the chunk packet + */ + private ChunkDataPacket createChunkPacket() { + final Map heightmaps; + lockWriteLock(); + try { + heightmaps = getHeightmaps(); + } finally { + unlockWriteLock(); + } + // Compute light data outside any locks. This *should* prevent deadlocks + final LightData lightData = createLightData(true); + + lockReadLock(); + try { + final NetworkBuffer.Type sectionSerializer = + ChunkData.Section.networkType(MinecraftServer.getBiomeRegistry().size()); + final byte[] data = NetworkBuffer.makeArray(networkBuffer -> { + for (Section section : this.storage.views()) { + final short blockCount = (short) section.blockPalette().count(); + final short liquidCount = (short) (blockCount > 0 ? 1 : 0); //TODO(26.1) proper fluid count + networkBuffer.write(sectionSerializer, + new ChunkData.Section(blockCount, liquidCount, section.blockPalette(), section.biomePalette())); + } + }); + + return new ChunkDataPacket(chunkX, chunkZ, + new ChunkData(heightmaps, data, this.entries), + lightData + ); + } finally { + unlockReadLock(); + } + } + + /** + * Collects the light arrays of the sections into the form the protocol wants. + *

+ * A section whose array is empty is reported as empty rather than as zeroed, which is the + * difference between "this section has no light data" and "this section is pitch black". + *

+ *

+ * The flag is unused here because this chunk always reports what it has. It is part of the + * signature so that a subclass which computes light can tell a full chunk send apart from a + * partial light update, which is the hook {@code LightingChunk} uses. + *

+ * + * @param requiredFullChunk true if the data is meant for a full chunk send + * @return the light data of this chunk + */ + protected LightData createLightData(boolean requiredFullChunk) { + final BitSet skyMask = new BitSet(); + final BitSet blockMask = new BitSet(); + final BitSet emptySkyMask = new BitSet(); + final BitSet emptyBlockMask = new BitSet(); + final List skyLights = new ArrayList<>(); + final List blockLights = new ArrayList<>(); + + int index = 0; + for (Section section : this.storage.views()) { + index++; + final byte[] skyLight = section.skyLight().array(); + final byte[] blockLight = section.blockLight().array(); + if (skyLight.length != 0) { + skyLights.add(skyLight); + skyMask.set(index); + } else { + emptySkyMask.set(index); + } + if (blockLight.length != 0) { + blockLights.add(blockLight); + blockMask.set(index); + } else { + emptyBlockMask.set(index); + } + } + return new LightData( + skyMask, blockMask, + emptySkyMask, emptyBlockMask, + skyLights, blockLights + ); + } + + /** + * Hands out both heightmaps in the form the chunk packet wants. + * + * @return the heightmaps of this chunk, keyed by their type + */ + protected Map getHeightmaps() { + assertReadLock(); + if (this.needsCompleteHeightmapRefresh) calculateFullHeightmap(); + final Heightmap motion = motionBlockingHeightmap(); + final Heightmap surface = worldSurfaceHeightmap(); + return Map.of( + motion.type(), motion.getNBT(), + surface.type(), surface.getNBT() + ); + } + + /** + * Reports the world height at which a heightmap scan of this chunk may start. + *

+ * The body of {@code Heightmap#getHighestBlockSection} with one substitution: it reaches its + * sections through {@code Chunk#getSection(int)}, which is the boundary that hands a section to + * an arbitrary caller and therefore has to create one. Walking a chunk from the build limit + * downwards through that method materialises exactly the empty top sections this chunk exists not + * to hold, on the first block anybody writes into it. Reading through + * {@link BlockStorage#view(int)} answers the same question and creates nothing. + *

+ *

+ * The arithmetic is copied rather than re-derived, including the descent by one section per step + * and the break on the first palette whose count is not zero, because the two have to agree: a + * heightmap computed from a different starting height than Minestom's is not a faster heightmap, + * it is a different one. + *

+ *

+ * It is public because a copy of an algorithm needs a caller that can check it and a harness that + * can measure it, and neither of the two lives in this class. {@code FalcoChunkEquivalenceTest} + * runs the result against {@code Heightmap#getHighestBlockSection(Chunk)} on a chunk holding the + * same blocks, which is the only assertion that reaches this body directly rather than through + * whatever heightmap happens to be refreshed; and {@code ChunkComparisonBenchmark} reproduces + * {@code calculateFullHeightmap} through public API, so without this method its Falco arm would + * have to start its scan from Minestom's static helper — which walks this chunk through + * {@link #getSection(int)} and materialises what it walks over. That is a scan this chunk no + * longer performs and an allocation profile it no longer has, so the figure would describe a + * chunk that does not exist. + *

+ *

+ * The caller has to hold the read lock of this chunk. + *

+ * + * @return the world Y at which the scan starts + */ + public int highestBlockSection() { + assertReadLock(); + int y = instance.getCachedDimensionType().maxY(); + + for (int index = this.storage.sectionCount() - 1; index >= 0; index--) { + if (this.storage.view(index).blockPalette().count() != 0) break; + y -= CHUNK_SECTION_SIZE; + } + return y; + } + + /** + * Rebuilds both heightmaps from the blocks of this chunk. + *

+ * The scan starts at the highest section that holds anything, so an empty chunk costs nothing and + * a chunk with a low world costs only what it fills. + *

+ */ + private void calculateFullHeightmap() { + assertWriteLock(); + final int startY = highestBlockSection(); + motionBlockingHeightmap().refresh(startY); + worldSurfaceHeightmap().refresh(startY); + this.needsCompleteHeightmapRefresh = false; + } } diff --git a/falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoInstance.java b/falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoInstance.java index c2fc1e5..34f231b 100644 --- a/falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoInstance.java +++ b/falco-instance/src/main/java/net/onelitefeather/falco/instance/FalcoInstance.java @@ -1,49 +1,22 @@ package net.onelitefeather.falco.instance; -import it.unimi.dsi.fastutil.ints.Int2ObjectMap; import net.kyori.adventure.key.Key; -import net.kyori.adventure.nbt.CompoundBinaryTag; import net.minestom.server.MinecraftServer; -import net.minestom.server.coordinate.BlockVec; -import net.minestom.server.coordinate.CoordConversion; import net.minestom.server.coordinate.Point; -import net.minestom.server.coordinate.Vec; -import net.minestom.server.entity.Entity; import net.minestom.server.entity.Player; -import net.minestom.server.event.EventDispatcher; -import net.minestom.server.event.instance.InstanceBlockUpdateEvent; -import net.minestom.server.event.instance.InstanceChunkLoadEvent; -import net.minestom.server.event.instance.InstanceChunkUnloadEvent; -import net.minestom.server.event.player.PlayerBlockBreakEvent; import net.minestom.server.instance.Chunk; import net.minestom.server.instance.ChunkLoader; -import net.minestom.server.instance.DynamicChunk; -import net.minestom.server.instance.EntityTracker; import net.minestom.server.instance.Instance; import net.minestom.server.instance.InstanceManager; -import net.minestom.server.instance.Section; import net.minestom.server.instance.block.Block; -import net.minestom.server.instance.block.BlockEntityType; import net.minestom.server.instance.block.BlockFace; import net.minestom.server.instance.block.BlockHandler; -import net.minestom.server.instance.block.rule.BlockPlacementRule; -import net.minestom.server.instance.generator.GenerationUnit; import net.minestom.server.instance.generator.Generator; -import net.minestom.server.instance.generator.GeneratorImpl; -import net.minestom.server.instance.palette.Palette; -import net.minestom.server.network.packet.server.play.BlockChangePacket; -import net.minestom.server.network.packet.server.play.BlockEntityDataPacket; -import net.minestom.server.network.packet.server.play.UnloadChunkPacket; -import net.minestom.server.network.packet.server.play.WorldEventPacket; import net.minestom.server.registry.Registries; import net.minestom.server.timer.SchedulerManager; import net.minestom.server.registry.RegistryKey; -import net.minestom.server.utils.PacketSendingUtils; -import net.minestom.server.utils.block.BlockUtils; -import net.minestom.server.utils.chunk.ChunkCache; import net.minestom.server.utils.chunk.ChunkSupplier; import net.minestom.server.world.DimensionType; -import net.minestom.server.worldevent.WorldEvent; import org.jetbrains.annotations.ApiStatus; import org.jetbrains.annotations.Contract; import org.jetbrains.annotations.Nullable; @@ -51,72 +24,123 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; -import java.util.ArrayList; -import java.util.Arrays; import java.util.Collection; -import java.util.Collections; -import java.util.List; -import java.util.Map; import java.util.Objects; import java.util.UUID; import java.util.concurrent.CompletableFuture; -import java.util.concurrent.ConcurrentHashMap; -import java.util.concurrent.atomic.AtomicBoolean; -import java.util.concurrent.atomic.AtomicReference; import java.util.function.Consumer; /** - * The {@link FalcoInstance} class is a world of a Minestom server which cleans up after itself. + * The {@link FalcoInstance} class is a world of a Minestom server which cleans up after itself, and + * it is a facade: it declares four references and nothing else. + * + *

The four parts and where the line between them runs

+ *
    + *
  • {@link ChunkRegistry} — which chunk sits at which position, and which position is busy. It + * holds the two maps and the four transitions between them, and it is the only thing that decides + * whether a position is free, loading or taken.
    • + *
  • {@link ChunkLifecycle} — everything that happens to a chunk between not existing and not + * existing again: create, read, publish, notify, unload, and the two settings that steer them. It + * uses the registry to make those transitions; it does not duplicate them. {@link ChunkGeneration} + * is its collaborator rather than a fifth part of this class, because a chunk is generated exactly + * once and that once is inside its load, and it is reached through + * {@link ChunkLifecycle#generation()}.
    • + *
  • {@link BlockWriter} — a block write and everything it wakes: the neighbours, the packets, the + * event, the recursion guard and the change timestamp.
    • + *
  • {@link ChunkPersistence} — the loader, the four save paths, the read and the unload + * notification, plus the two settings the shutdown of this instance asks it about.
    • + *
*

- * It extends {@link Instance} directly instead of {@code InstanceContainer}. Deriving from the - * container looks cheaper but leads nowhere: the chunk lifecycle hooks it would have to override - * are {@code protected} members of {@code net.minestom.server.instance}, so a subclass in this - * package cannot reach them. Starting from {@link Instance} makes the same barrier visible once, at - * the chunk, where {@link FalcoChunk} answers it. + * The line between them is the one worth stating, because it is the one a later change is most likely + * to blur: a part holds whatever it needs to answer its own question, and it never holds a reference + * to another part it was not handed. {@link ChunkLifecycle} is handed the registry, the persistence + * and the generation rather than reaching for them, which is what lets each of the four be driven on + * its own by a test — US-3.02, and the reason the split was worth six commits. *

*

- * Four places in Minestom branch on {@code instanceof InstanceContainer} and quietly take a - * different path for any other instance. Three of them are harmless here, one is not: + * That is a rule about references, not a claim that the four never look at each other. Two of them do, + * both through this class rather than through a field, and they are named here because a rule with two + * exceptions nobody wrote down is a rule that gets discovered by breaking it: + *

+ *
    + *
  • {@link BlockWriter#setBlock(int, int, int, Block, boolean)} asks + * {@link ChunkLifecycle#autoLoad()} whether it may load the chunk it is about to write into. + * The setting steers a load, so it belongs to the lifecycle; the question is asked on the write + * path, so the writer has to ask it.
    • + *
  • {@link ChunkLifecycle#create(int, int)} calls {@link #refreshLastBlockChangeTime()} after a + * generator filled a chunk, and this class forwards that to {@link BlockWriter}, which keeps the + * timestamp because every other writer of it is a block write.
    • + *
+ *

+ * Both couplings predate this class becoming a facade and neither is a reference: each goes through a + * public method of the other part, so either part can still be constructed and driven alone. A change + * to {@code autoLoad} or to the timestamp has to be checked against the part on the other side. + *

+ * + *

Why this class declares nothing but its parts

+ *

+ * A facade that keeps state of its own is the class it replaced with delegation in front of it, and + * the difference is invisible from the outside: every method below still reads like a one-liner while + * a fifth field quietly makes two parts disagree. That is not left to a reader. + * {@code InstanceFacadeTest} asks {@code getDeclaredFields()} on every build and fails if this class + * declares anything but one {@code final} reference per part. Anything that looks like it belongs here + * belongs in one of the four instead; if it belongs in none of them, the split is wrong and needs a + * fifth part rather than a field. + *

+ *

+ * What that test asserts is the declaration and only the declaration, which is narrower than the + * facade holds no state: {@link ChunkPersistence#saveOnShutdown()} and + * {@link ChunkPersistence#ownsLoader()} are read by {@link #shutdown(InstanceManager)} and by nothing + * else, so a value the facade acts on does live one hop away. That is stated rather than glossed over, + * and the reason it is still the right home is written at {@link ChunkPersistence}. + *

+ * + *

What being an {@link Instance} rather than a container costs

+ *

+ * This class extends {@link Instance} directly instead of {@code InstanceContainer}. Deriving from the + * container looks cheaper but leads nowhere: the chunk lifecycle hooks it would have to override are + * {@code protected} members of {@code net.minestom.server.instance}, so a subclass in this package + * cannot reach them. Starting from {@link Instance} makes the same barrier visible once, at the chunk, + * where {@link FalcoChunk} answers it. + *

+ *

+ * Four places in Minestom branch on {@code instanceof InstanceContainer} and quietly take a different + * path for any other instance. The split changed none of them, so all four still apply exactly as they + * did. Three are harmless here, one is not: *

*
    *
  • {@code InstanceManager#unregisterInstance} does not unload the chunks of a foreign * instance, which leaks every chunk the instance ever loaded. {@link #unregister(InstanceManager)} - * is the answer and the reason this class exists.
    • + * is the answer and it is still the reason this class exists — the four parts are how it is built, + * not why. *
  • {@code SharedInstance} is typed on the container throughout, so this instance cannot back * one. That is a missing feature rather than a defect, and it is refused by the compiler.
    • *
  • The {@code Chunk} constructor asks the instance for its shared instances and gets an empty * list here. Since there are no shared instances, an empty list is the correct answer.
    • - *
  • The block batches skip {@code refreshLastBlockChangeTime()} for a foreign instance. This - * class keeps the timestamp itself, but nothing outside it refreshes it, so batch copies must not - * rely on it.
    • + *
  • The block batches skip {@code refreshLastBlockChangeTime()} for a foreign instance. + * {@link BlockWriter} keeps the timestamp, but nothing outside it refreshes it, so batch copies + * must not rely on it.
    • *
*

- * A world here comes from its {@link ChunkLoader}, from a {@link Generator}, or stays empty, in that - * order. The generator runs against staged palettes rather than against the live ones of the chunk, - * so a generator which fails halfway changes nothing and the failure reaches the caller instead of - * the exception manager. {@code InstanceContainer} does the opposite on both counts, which is why - * {@link #generator()} could not simply be inherited in spirit. - *

- *

- * The other place where this class deviates on purpose is the moment a loaded chunk becomes part of - * the instance. Publishing a chunk and unloading one are two transitions of the same position, and - * they are made mutually exclusive, so an unload which meets a running load either sees the finished - * chunk or claims the load and makes it throw its result away. Minestom lets the two overlap, and - * the chunk which loses that race stays in the world with nothing left that could unload it. + * Where this class deviates from {@code InstanceContainer} on purpose — the generator that runs + * against staged palettes instead of the live ones, the publish and the unload of one position that + * are made mutually exclusive, and the block write that takes the lock of one chunk instead of a + * monitor on the whole world — the reasoning now sits with the code it is about, in + * {@link ChunkGeneration#apply(Chunk, Generator)}, {@link ChunkLifecycle} and {@link BlockWriter} + * respectively. It moved with them rather than being dropped: a comment about a lock is worth + * something only next to the statement that takes it. *

*

- * On threading, this class promises no more than Minestom does, and for a reason worth stating: the + * On threading this class promises no more than Minestom does, and for a reason worth stating: the * parallelism of chunk and entity ticking lives in the global {@code ThreadDispatcher} of the server - * process, not in the instance. Replacing the instance cannot make ticking faster. What it does buy - * is that block writes are guarded by the lock of the chunk they touch rather than by a monitor on - * the whole instance, so two writes to two chunks no longer wait for each other. + * process, not in the instance. Replacing the instance cannot make ticking faster. *

*

* This type is experimental. The instance module is new and its API may still change. *

* * @author TheMeinerLP - * @version 1.0.0 + * @version 2.1.0 * @since 0.1.0 */ @ApiStatus.Experimental @@ -124,13 +148,6 @@ public class FalcoInstance extends Instance { private static final Logger LOGGER = LoggerFactory.getLogger(FalcoInstance.class); - /** - * The faces a block change offers to its neighbours for a placement rule update. - */ - private static final BlockFace[] BLOCK_UPDATE_FACES = { - BlockFace.WEST, BlockFace.EAST, BlockFace.NORTH, BlockFace.SOUTH, BlockFace.BOTTOM, BlockFace.TOP - }; - /** * The depth below the bottom of the dimension at which a point counts as being in the void. */ @@ -149,128 +166,63 @@ public class FalcoInstance extends Instance { private static final int UNREGISTER_PASSES = 4; /** - * The loaded chunks, keyed by the chunk index of their position. - *

- * A plain concurrent hash map rather than the synchronised long map of the container: chunk - * streaming is a lookup-dominated access pattern, and the copy-on-write map underneath the - * container pays for every load and unload instead. - *

- */ - private final Map chunks = new ConcurrentHashMap<>(); - - /** - * The chunks which are being loaded right now, keyed by chunk index. - *

- * Holding the future rather than a flag is what makes two concurrent requests for the same - * chunk share one load instead of racing into two chunk objects. - *

- *

- * This map is also the lock of a chunk position. Every transition of a position — starting a - * load, publishing its result, unloading the chunk again — happens inside a - * {@link ConcurrentHashMap#compute} on the index of that position, which serialises them without - * putting a monitor over the whole instance. That is what the entry of a position is worth far - * more than the future it holds: without it, an unload and the load it races can both believe - * they went first, and the chunk which loses ends up in the instance with its loaded flag - * already cleared, where nothing will ever unload it again. - *

- */ - private final Map> loadingChunks = new ConcurrentHashMap<>(); - - /** - * The section modifiers a generator produced for chunks which were not loaded at the time, - * keyed by the chunk index of the chunk they belong to. - *

- * A generator may write outside the chunk it was asked about through - * {@link GenerationUnit#fork(java.util.function.Consumer)}. Those writes cannot be applied yet - * when their target does not exist, and dropping them would make a generator produce different - * worlds depending on the order in which chunks happened to be requested. - *

- */ - private final Map> generationForks = new ConcurrentHashMap<>(); - - /** - * The registries the biomes of a generated chunk are looked up in. + * Which chunk sits at which position, and which position is busy. *

- * Kept here rather than read from {@link MinecraftServer} so an instance built against a process - * which is not the global one generates against the registries of that process. + * The two maps behind this and the four transitions between them used to be fields and + * {@code private} methods of this class. They are a responsibility rather than a detail of the + * instance, and {@link ChunkRegistry} carries both the answer and the state it needs to give it, + * so nothing of the chunk map is left here to be shared with anything else. *

- */ - private final Registries registries; - - /** - * The generator which fills a chunk no loader knows about, null while the world stays empty. - */ - private volatile @Nullable Generator generator; - - /** - * The blocks changed since the last tick, used to break recursion between block handlers. *

- * Concurrent rather than a plain map behind a lock that guarded nothing, which is the shape the - * container has. + * That the map of running loads is also the lock of a position is stated where the transitions + * are, in {@link ChunkRegistry}, and the steps handed to {@link ChunkRegistry#publish} and + * {@link ChunkRegistry#remove} come from {@link ChunkLifecycle}. *

*/ - private final Map currentlyChangingBlocks = new ConcurrentHashMap<>(); + private final ChunkRegistry registry; /** - * The factory every chunk of this instance is created by. + * Everything this instance does when a block changes. *

- * Volatile because the setter is public and unsynchronized while the load path reads the field - * from a chunk task on another thread. Without it the reader may not only miss the change, it - * may see a half-constructed supplier: the value is an arbitrary object handed in by a caller, - * and only a volatile write publishes that object safely. Synchronizing the setter instead - * would put a lock on the monitor of a public object, which is exactly what callers must not be - * able to hold against this instance. + * The three entry points, the write, the neighbour pass, the packets, the event, the recursion + * guard and the change timestamp used to be members of this class, and the ordering they promise — + * the write lock of one chunk held across the write and across nothing else — was a property of + * one {@code private} method nobody could drive on its own. {@link BlockWriter} carries all of it, + * which is what makes that ordering something a test can measure. *

*/ - private volatile ChunkSupplier chunkSupplier = FalcoChunk::new; + private final BlockWriter blockWriter; /** - * The loader chunks of this instance are read from and written to, a no-op loader when the - * instance was built without one. + * Everything this instance does with a {@link ChunkLoader}: the four save paths, the read and the + * notification that a chunk left. *

- * Volatile for the same reason as {@link #chunkSupplier}: written by a public unsynchronized - * setter, read on the load path from another thread, and the value is a caller object whose - * construction has to be visible to that reader. + * Final, and the loader inside it is what changes. The field which used to sit here was + * {@code volatile} because a public setter wrote it while the load path read it from another + * thread; that reason did not go away, it moved into {@link ChunkPersistence} along with the + * loader. *

*/ - private volatile ChunkLoader chunkLoader; - - private volatile boolean autoChunkLoad = true; - - private volatile long lastBlockChangeTime; + private final ChunkPersistence persistence; /** - * How a chunk of this instance is told that it was loaded, or null for the built-in way. + * Everything that happens to a chunk between not existing and not existing again, and what fills a + * chunk no loader knows about. *

- * {@code Chunk#onLoad()} and {@code Chunk#unload()} are {@code protected}, so this package can - * drive them only on {@link FalcoChunk}, a type it defines itself. A caller that owns another - * chunk type — a lighting chunk from {@code falco-light}, say — can reach both hooks and hands - * them over here. Null means the built-in pair, which requires a {@link FalcoChunk} exactly as - * before. + * The create, the read, the publish, the unload and the two settings which steer them — + * the chunk supplier and the auto load flag — used to be {@code private} members of this class, + * which meant that a publish could only be reached by driving a whole load through a loader. They + * are a responsibility of their own and {@link ChunkLifecycle} carries it, which is what makes + * each step reachable and measurable one at a time. *

*

- * Volatile for the same reason as {@link #chunkSupplier}: a caller object written by a public - * setter and read on the load path from another thread. + * {@link ChunkGeneration} is held by this part rather than beside it, and is reached through + * {@link ChunkLifecycle#generation()}. A chunk is generated exactly once and that once is inside + * its load, so a field here would have been a fifth reference nothing but the lifecycle ever + * touches. *

*/ - private volatile @Nullable Consumer chunkLoaded; - - /** - * How a chunk of this instance is told that it left, or null for the built-in way. - * - * @see #chunkLoaded - */ - private volatile @Nullable Consumer chunkUnloaded; - - /** - * Whether {@link #shutdown(InstanceManager)} saves the chunks before it unregisters. - */ - private volatile boolean saveOnShutdown = true; - - /** - * Whether {@link #shutdown(InstanceManager)} closes the loader, if the loader can be closed. - */ - private volatile boolean ownsLoader; + private final ChunkLifecycle lifecycle; /** * Creates an instance in the overworld dimension without a chunk loader. @@ -311,10 +263,21 @@ public FalcoInstance(UUID uuid, RegistryKey dimensionType, @Nulla public FalcoInstance(Registries registries, UUID uuid, RegistryKey dimensionType, @Nullable ChunkLoader loader, Key dimensionName) { super(registries, uuid, dimensionType, dimensionName); - this.registries = registries; - this.chunkLoader = Objects.requireNonNullElseGet(loader, ChunkLoader::noop); - this.chunkLoader.loadInstance(this); - this.lastBlockChangeTime = System.nanoTime(); + this.registry = new ChunkRegistry(); + this.persistence = new ChunkPersistence(loader); + this.blockWriter = new BlockWriter(this); + // The registries are handed straight through rather than kept. They are what the biomes of a + // generated chunk are looked up in, generation is the only thing that asks, and this is the + // only line that hands them over — a field for them would be state of the facade that nothing + // reads twice. Taken as an argument rather than read from MinecraftServer so an instance built + // against a process which is not the global one generates against the registries of that + // process. ChunkGeneration is handed getChunkAt rather than this instance, because a neighbour + // a fork writes into is the only thing generation ever needs a world for. + this.lifecycle = new ChunkLifecycle(this, this.registry, this.persistence, + new ChunkGeneration(registries, this::getChunkAt)); + // Last, and outside every constructor above: loadInstance may call back into this instance, + // and a callback into an object whose parts are not all built yet reads one of them as null. + this.persistence.loader().loadInstance(this); } /** @@ -356,7 +319,7 @@ public static Builder builder(RegistryKey dimensionType) { * @throws FalcoInstanceException if the chunks could not be saved or the loader not closed */ public void shutdown(InstanceManager instanceManager) { - if (this.saveOnShutdown) { + if (this.persistence.saveOnShutdown()) { try { saveChunksToStorage().join(); } catch (Throwable throwable) { @@ -366,9 +329,9 @@ public void shutdown(InstanceManager instanceManager) { } unregister(instanceManager); - if (!this.ownsLoader) return; + if (!this.persistence.ownsLoader()) return; - if (this.chunkLoader instanceof AutoCloseable closeable) { + if (this.persistence.loader() instanceof AutoCloseable closeable) { try { closeable.close(); } catch (Exception exception) { @@ -413,549 +376,141 @@ public void shutdown(InstanceManager instanceManager) { public void unregister(InstanceManager instanceManager) { if (isRegistered()) instanceManager.unregisterInstance(this); for (int pass = 0; pass < UNREGISTER_PASSES; pass++) { - for (Long index : List.copyOf(this.loadingChunks.keySet())) discardRunningLoad(index); - for (Chunk chunk : List.copyOf(this.chunks.values())) unloadChunk(chunk); - if (this.loadingChunks.isEmpty() && this.chunks.isEmpty()) { + for (Long index : this.registry.loadingPositions()) this.lifecycle.discard(index); + for (Chunk chunk : this.registry.snapshot()) this.lifecycle.unload(chunk); + if (this.registry.idle()) { // A fork whose target chunk was never requested waits forever, and after this there // is nothing left it could wait for. - this.generationForks.clear(); + this.lifecycle.generation().clearPending(); return; } } - this.generationForks.clear(); + this.lifecycle.generation().clearPending(); LOGGER.warn("chunks kept arriving while the instance {} was unregistered; {} chunks and {} loads are left behind", - getUuid(), this.chunks.size(), this.loadingChunks.size()); + getUuid(), this.registry.size(), this.registry.loading()); } /** - * Takes the slot of a running load so its chunk never reaches this instance. + * Hands out the registry of chunk positions of this instance. *

- * Removing the entry is the whole claim: the loading thread publishes its chunk only while its - * own future is still the entry of the position, so a load which finds the slot empty or taken - * knows that somebody decided its result is no longer wanted. The waiting callers are told with - * a failure rather than with the chunk, because a chunk which is handed back after it was - * discarded looks usable and is not. + * Exposed because a facade whose parts cannot be reached is a facade whose parts cannot be + * tested, which is the whole reason this class was split. *

* - * @param index the chunk index of the position whose load is claimed + * @return the registry of this instance + * @since 0.4.0 */ - private void discardRunningLoad(long index) { - final CompletableFuture running = this.loadingChunks.remove(index); - if (running == null) return; - running.completeExceptionally(new FalcoInstanceException("the chunk " - + CoordConversion.chunkIndexGetX(index) + ":" + CoordConversion.chunkIndexGetZ(index) - + " was unloaded while it was being loaded, so the load was cancelled")); - } - - @Override - public void setBlock(int x, int y, int z, Block block, boolean doBlockUpdates) { - Chunk chunk = getChunkAt(x, z); - if (chunk == null) { - if (!this.autoChunkLoad) { - throw new IllegalStateException( - "tried to set a block in the unloaded chunk " + CoordConversion.globalToChunk(x) - + ":" + CoordConversion.globalToChunk(z) + " while auto chunk load is disabled"); - } - chunk = loadChunk(CoordConversion.globalToChunk(x), CoordConversion.globalToChunk(z)).join(); - } - if (chunk.isLoaded()) writeBlock(requireManagedChunk(chunk), x, y, z, block, null, null, doBlockUpdates, 0); - } - - @Override - public boolean placeBlock(BlockHandler.Placement placement, boolean doBlockUpdates) { - final Point blockPosition = placement.getBlockPosition(); - final Chunk chunk = getChunkAt(blockPosition); - if (chunk == null || !chunk.isLoaded()) return false; - writeBlock(requireManagedChunk(chunk), blockPosition.blockX(), blockPosition.blockY(), blockPosition.blockZ(), - placement.getBlock(), placement, null, doBlockUpdates, 0); - return true; + public ChunkRegistry registry() { + return this.registry; } - @Override - public boolean breakBlock(Player player, Point blockPosition, BlockFace blockFace, boolean doBlockUpdates) { - final Chunk chunk = getChunkAt(blockPosition); - if (chunk == null || !chunk.isLoaded() || chunk.isReadOnly()) return false; - - final Block block = getBlock(blockPosition); - if (block.isAir()) { - // The client believes there is a block here; hand it the chunk it actually has. - chunk.sendChunk(player); - return false; - } - final PlayerBlockBreakEvent event = new PlayerBlockBreakEvent(player, this, block, Block.AIR, - blockPosition.asBlockVec(), blockFace); - EventDispatcher.call(event); - if (event.isCancelled()) return false; - - final Block resultBlock = event.getResultBlock(); - writeBlock(requireManagedChunk(chunk), blockPosition.blockX(), blockPosition.blockY(), blockPosition.blockZ(), resultBlock, - null, new BlockHandler.PlayerDestroy(block, resultBlock, this, blockPosition, player), - doBlockUpdates, 0); - PacketSendingUtils.sendGroupedPacket(chunk.getViewers(), - new WorldEventPacket(WorldEvent.PARTICLES_DESTROY_BLOCK.id(), blockPosition, block.stateId(), false), - // The breaking player already played the effect locally. - viewer -> !viewer.equals(player)); - return true; + /** + * Hands out the lifecycle of the chunks of this instance. + * + * @return the lifecycle of this instance + * @since 0.4.0 + */ + public ChunkLifecycle lifecycle() { + return this.lifecycle; } /** - * Writes a block into a chunk and tells everyone who needs to know. + * Hands out the block writer of this instance. *

- * Only the write lock of the touched chunk is held here. The container of Minestom takes its own - * monitor around the whole method, which turns every block write in the world into a queue - * behind every other one; two writes to two chunks have no reason to wait for each other. - *

- *

- * The chunk is taken as a {@link FalcoChunk} rather than a {@link Chunk} because the block - * setter carrying a placement and a destruction is {@code protected} on {@code Chunk} and only - * widened to public by {@code DynamicChunk}. That is a third lifecycle barrier next to the two - * hooks {@link FalcoChunk} re-exposes, and it is answered the same way. + * Exposed for the same reason as {@link #registry()}: the ordering {@link BlockWriter} promises + * around the lock of a chunk can only be measured by a caller which can drive one write on its + * own, and no entry point of this class offers that. *

* - * @param chunk the chunk which receives the block, has to be loaded - * @param x the block X - * @param y the block Y - * @param z the block Z - * @param block the block to write - * @param placement the placement which caused the write, null if it was not a placement - * @param destroy the destruction which caused the write, null if it was not a break - * @param doBlockUpdates true to let the neighbours of the block reshape themselves - * @param updateDistance how many neighbour updates deep this write already is + * @return the block writer of this instance + * @since 0.4.0 */ - private void writeBlock(DynamicChunk chunk, int x, int y, int z, Block block, - @Nullable BlockHandler.Placement placement, @Nullable BlockHandler.Destroy destroy, - boolean doBlockUpdates, int updateDistance) { - if (chunk.isReadOnly()) return; - final DimensionType dimension = getCachedDimensionType(); - if (y >= dimension.maxY() || y < dimension.minY()) { - LOGGER.warn("tried to set a block outside the world bounds, should be within [{}, {}): {}", - dimension.minY(), dimension.maxY(), y); - return; - } - final BlockVec blockPosition = new BlockVec(x, y, z); - // A handler which destroys its own block would otherwise recurse until the stack ends. - if (Objects.equals(this.currentlyChangingBlocks.get(blockPosition), block)) return; - this.currentlyChangingBlocks.put(blockPosition, block); - - Block placed = block; - chunk.lockWriteLock(); - try { - this.lastBlockChangeTime = System.nanoTime(); - final BlockPlacementRule rule = MinecraftServer.getBlockManager().getBlockPlacementRule(placed); - if (placement != null && rule != null && doBlockUpdates) { - placed = Objects.requireNonNullElse(rule.blockPlace(placementState(placement, placed, blockPosition)), Block.AIR); - } - chunk.setBlock(x, y, z, placed, placement, destroy); - } finally { - chunk.unlockWriteLock(); - } - - // Outside the chunk lock on purpose: a neighbour may live in another chunk, and taking a - // second chunk lock while holding the first is how two block writes deadlock each other. - if (doBlockUpdates) updateNeighbours(blockPosition, updateDistance); - - chunk.sendPacketToViewers(new BlockChangePacket(blockPosition, placed.stateId())); - final BlockEntityType blockEntityType = placed.registry().blockEntityType(); - if (blockEntityType != null) { - final CompoundBinaryTag data = BlockUtils.extractClientNbt(placed); - chunk.sendPacketToViewers(new BlockEntityDataPacket(blockPosition, blockEntityType, data)); - } - EventDispatcher.call(new InstanceBlockUpdateEvent(this, blockPosition, placed)); + public BlockWriter blockWriter() { + return this.blockWriter; } - /** - * Builds the state a placement rule is asked about. - * - * @param placement the placement which caused the write - * @param block the block which is about to be placed - * @param blockPosition the position the block goes to - * @return the state to hand to {@code BlockPlacementRule#blockPlace} - */ - @Contract("_, _, _ -> new") - private BlockPlacementRule.PlacementState placementState(BlockHandler.Placement placement, Block block, - Point blockPosition) { - if (placement instanceof BlockHandler.PlayerPlacement playerPlacement) { - final Player player = playerPlacement.getPlayer(); - return new BlockPlacementRule.PlacementState(this, block, playerPlacement.getBlockFace(), blockPosition, - new Vec(playerPlacement.getCursorX(), playerPlacement.getCursorY(), playerPlacement.getCursorZ()), - player.getPosition(), player.getItemInHand(playerPlacement.getHand()), player.isSneaking()); - } - return new BlockPlacementRule.PlacementState(this, block, null, blockPosition, null, null, null, false); + @Override + public void setBlock(int x, int y, int z, Block block, boolean doBlockUpdates) { + this.blockWriter.setBlock(x, y, z, block, doBlockUpdates); } - /** - * Lets the six neighbours of a changed block reshape themselves. - * - * @param blockPosition the position of the block which changed - * @param updateDistance how many neighbour updates deep the causing write already was - */ - private void updateNeighbours(Point blockPosition, int updateDistance) { - final ChunkCache cache = new ChunkCache(this, null, null); - final DimensionType dimension = getCachedDimensionType(); - for (BlockFace face : BLOCK_UPDATE_FACES) { - final var direction = face.toDirection(); - final int neighbourX = blockPosition.blockX() + direction.normalX(); - final int neighbourY = blockPosition.blockY() + direction.normalY(); - final int neighbourZ = blockPosition.blockZ() + direction.normalZ(); - if (neighbourY < dimension.minY() || neighbourY >= dimension.maxY()) continue; - final Block neighbour = cache.getBlock(neighbourX, neighbourY, neighbourZ, Condition.NONE); - if (neighbour == null || neighbour.isAir()) continue; - final BlockPlacementRule rule = MinecraftServer.getBlockManager().getBlockPlacementRule(neighbour); - if (rule == null || updateDistance >= rule.maxUpdateDistance()) continue; + @Override + public boolean placeBlock(BlockHandler.Placement placement, boolean doBlockUpdates) { + return this.blockWriter.placeBlock(placement, doBlockUpdates); + } - final Vec neighbourPosition = new Vec(neighbourX, neighbourY, neighbourZ); - final Block updated = rule.blockUpdate(new BlockPlacementRule.UpdateState( - this, neighbourPosition, neighbour, face.getOppositeFace())); - if (neighbour.equals(updated)) continue; - final Chunk neighbourChunk = getChunkAt(neighbourPosition); - if (neighbourChunk == null || !neighbourChunk.isLoaded()) continue; - writeBlock(requireManagedChunk(neighbourChunk), neighbourX, neighbourY, neighbourZ, updated, null, null, - true, updateDistance + 1); - } + @Override + public boolean breakBlock(Player player, Point blockPosition, BlockFace blockFace, boolean doBlockUpdates) { + return this.blockWriter.breakBlock(player, blockPosition, blockFace, doBlockUpdates); } @Override public CompletableFuture loadChunk(int chunkX, int chunkZ) { - return retrieveChunk(chunkX, chunkZ); + return this.lifecycle.retrieve(chunkX, chunkZ); } @Override public CompletableFuture<@Nullable Chunk> loadOptionalChunk(int chunkX, int chunkZ) { final Chunk loaded = getChunk(chunkX, chunkZ); if (loaded != null) return CompletableFuture.completedFuture(loaded); - if (!this.autoChunkLoad) return CompletableFuture.completedFuture(null); - return retrieveChunk(chunkX, chunkZ); - } - - /** - * Hands back the chunk at the given position, loading it if it is not there yet. - *

- * Two callers asking for the same chunk at the same time share one load: the first one to put - * its future into the map of loading chunks performs the work, everyone else receives that same - * future. The decision is taken inside a {@link ConcurrentHashMap#compute} on the position, and - * the chunk map is read a second time in there. Without that second read a caller which looked - * at the chunk map just before a load published, and reached this point just after that load - * removed its entry, would start a second load for a position which already has a chunk. The - * second chunk then replaces the first one in the map and the first one is orphaned: still - * marked as loaded, still holding its tick partition and its viewers, and no longer reachable. - *

- *

- * The work itself starts after the decision, never inside it. A loader without parallel support - * runs on the calling thread, and a nested {@code compute} on the same map would deadlock. - *

- *

- * A failure completes the returned future exceptionally and stops there. It is deliberately not - * also pushed into the exception manager of the server the way the container does it, because a - * failure that is both reported and returned gets handled twice and logged twice. - *

- * - * @param chunkX the chunk X - * @param chunkZ the chunk Z - * @return a future completed with the chunk, or completed exceptionally if it cannot be created - */ - private CompletableFuture retrieveChunk(int chunkX, int chunkZ) { - final long index = CoordConversion.chunkIndex(chunkX, chunkZ); - final Chunk loaded = this.chunks.get(index); - if (loaded != null) return CompletableFuture.completedFuture(loaded); - - final CompletableFuture own = new CompletableFuture<>(); - final AtomicReference published = new AtomicReference<>(); - final CompletableFuture slot = this.loadingChunks.compute(index, (_, running) -> { - if (running != null) return running; - final Chunk cached = this.chunks.get(index); - if (cached != null) { - published.set(cached); - return null; - } - return own; - }); - final Chunk cached = published.get(); - if (cached != null) return CompletableFuture.completedFuture(cached); - if (slot != own) return slot; - - final ChunkLoader loader = this.chunkLoader; - if (loader.supportsParallelLoading()) { - Thread.startVirtualThread(() -> completeLoad(index, chunkX, chunkZ, loader, own)); - } else { - // A loader without parallel support is read on the calling thread, which keeps a - // `loadChunk(…).join()` from a tick free of a thread hand-off it would only wait for. - completeLoad(index, chunkX, chunkZ, loader, own); - } - return own; - } - - /** - * Reads a chunk through the loader, publishes it and completes the waiting future. - *

- * The chunk is produced first and published second, and the publish may be refused. Everything - * in between the two is the window in which an unload can decide that this chunk is not wanted - * any more; a load which is refused therefore has to undo itself rather than complain, which is - * what the discard below does. - *

- * - * @param index the chunk index of the position, the key in the map of loading chunks - * @param chunkX the chunk X - * @param chunkZ the chunk Z - * @param loader the loader the chunk is read from - * @param future the future handed to the callers waiting for this chunk - */ - private void completeLoad(long index, int chunkX, int chunkZ, ChunkLoader loader, CompletableFuture future) { - final DynamicChunk falcoChunk; - try { - Chunk chunk = loader.loadChunk(this, chunkX, chunkZ); - if (chunk == null) { - chunk = createChunk(chunkX, chunkZ); - chunk.onGenerate(); - } - falcoChunk = requireManagedChunk(chunk); - } catch (Throwable throwable) { - this.loadingChunks.remove(index, future); - future.completeExceptionally(throwable); - return; - } - if (!publishChunk(index, falcoChunk, future)) { - // The chunk was never part of this instance, so there is no map entry and no partition - // to clean up. The loader is still told, because it created the chunk and may hold - // bookkeeping for it, which its own documentation allows for explicitly. - notifyUnloaded(falcoChunk); - this.chunkLoader.unloadChunk(falcoChunk); - future.completeExceptionally(new FalcoInstanceException("the chunk " + chunkX + ":" + chunkZ - + " was unloaded while it was being loaded, so the loaded chunk was discarded")); - return; - } - notifyLoaded(falcoChunk); - future.complete(falcoChunk); - EventDispatcher.call(new InstanceChunkLoadEvent(this, falcoChunk)); - } - - /** - * Makes a freshly loaded chunk part of this instance, unless somebody claimed its position. - *

- * Putting the chunk into the chunk map and giving it a tick partition are one step, taken while - * the position is held, so an unload of the same position can only run entirely before or - * entirely after it. Splitting them is what lets Minestom delete a partition that is created a - * moment later, which leaves the chunk being ticked for the rest of the life of the server even - * though nothing else knows about it any more. - *

- *

- * The loaded flag of the chunk is deliberately set outside, because it calls a hook a subclass - * may override, and foreign code has no business running while a position is held. - *

- * - * @param index the chunk index of the position - * @param chunk the chunk to publish - * @param future the future of this load, which has to still be the entry of the position - * @return true if the chunk is now part of this instance, false if the load was claimed - */ - private boolean publishChunk(long index, DynamicChunk chunk, CompletableFuture future) { - final AtomicBoolean published = new AtomicBoolean(); - this.loadingChunks.compute(index, (_, running) -> { - if (running != future) return running; - this.chunks.put(index, chunk); - MinecraftServer.process().dispatcher().createPartition(chunk); - published.set(true); - return null; - }); - return published.get(); - } - - /** - * Creates a chunk through the chunk supplier of this instance and generates it. - *

- * This is the path a chunk takes which no {@link ChunkLoader} knows about. Without a generator - * the chunk stays empty, which is a world made of air rather than a failure. - *

- * - * @param chunkX the chunk X - * @param chunkZ the chunk Z - * @return the created chunk - * @throws FalcoInstanceException if the chunk supplier returned null - */ - protected Chunk createChunk(int chunkX, int chunkZ) { - final Chunk chunk = this.chunkSupplier.createChunk(this, chunkX, chunkZ); - if (chunk == null) { - throw new FalcoInstanceException("the chunk supplier returned null for chunk " + chunkX + ":" + chunkZ); - } - final Generator current = this.generator; - if (current != null && chunk.shouldGenerate()) { - applyGenerator(chunk, current); - } else { - applyPendingForks(chunk); - } - return chunk; - } - - /** - * Checks that a chunk is one this instance can manage. - *

- * A chunk of any other type would be accepted by everything except the unload path, where the - * {@code protected} lifecycle hooks are out of reach, so it would silently keep reporting itself - * as loaded forever. Refusing it here names the cause at the point where the wrong supplier was - * used. - *

- * - * @param chunk the chunk to check - * @return the same chunk, typed - * @throws FalcoInstanceException if the chunk is not a {@link FalcoChunk} - */ - @Contract("_ -> param1") - private DynamicChunk requireManagedChunk(Chunk chunk) { - if (this.chunkLoaded == null || this.chunkUnloaded == null) { - if (chunk instanceof FalcoChunk falcoChunk) return falcoChunk; - throw new FalcoInstanceException("this instance only manages " + FalcoChunk.class.getName() - + ", but its chunk supplier produced a " + chunk.getClass().getName() - + "; the lifecycle hooks of any other chunk cannot be reached from this package." - + " Configure setChunkLifecycle if you own the chunk type and can reach them"); - } - if (chunk instanceof DynamicChunk dynamicChunk) return dynamicChunk; - throw new FalcoInstanceException("this instance manages subtypes of " - + DynamicChunk.class.getName() + ", but its chunk supplier produced a " - + chunk.getClass().getName()); - } - - /** - * Tells a chunk that it is now part of this instance. - * - * @param chunk the chunk which finished loading - */ - private void notifyLoaded(DynamicChunk chunk) { - @Nullable Consumer configured = this.chunkLoaded; - - if (configured == null) { - ((FalcoChunk) chunk).markLoaded(); - return; - } - configured.accept(chunk); - } - - /** - * Tells a chunk that it is no longer part of this instance. - * - * @param chunk the chunk which left the instance - */ - private void notifyUnloaded(DynamicChunk chunk) { - @Nullable Consumer configured = this.chunkUnloaded; - - if (configured == null) { - ((FalcoChunk) chunk).markUnloaded(); - return; - } - configured.accept(chunk); + if (!this.lifecycle.autoLoad()) return CompletableFuture.completedFuture(null); + return this.lifecycle.retrieve(chunkX, chunkZ); } /** * Removes a chunk from this instance. *

- * Taking the chunk out of the chunk map, clearing its loaded flag and deleting its tick - * partition are one step, taken while the position of the chunk is held, so a load which is - * publishing the same position cannot interleave with it. Everything else — the packet, the - * event, the entities and the loader — follows outside, because all four can call back into this - * instance and holding a position while foreign code runs is how two chunks deadlock each other. - *

- *

- * A running load is not cancelled here and not waited for either, and that is not an omission: a - * position which is loading has no chunk in the map, so a chunk a caller can hand to this method - * is never the one being loaded. It is either the chunk of that position, which the atomic step - * below removes, or a chunk of an earlier life of that position, which was already unloaded and - * is refused by the first line. Cancelling a load needs a position rather than a chunk, and - * {@link #unregister(InstanceManager)} is where that happens. + * What that means step by step, and which of the steps runs while the position of the chunk is + * held, is documented on {@link ChunkLifecycle#unload(Chunk)}; this is the door + * {@code Instance} demands. *

*

* Unloading the same chunk twice does nothing the second time, which makes this usable in a * cleanup path that may run more than once. *

* - * @param chunk the chunk to remove, has to be a {@link FalcoChunk} - * @throws FalcoInstanceException if the chunk is not a {@link FalcoChunk} + * @param chunk the chunk to remove, has to be a {@link FalcoChunk} unless a lifecycle pair was + * installed through {@link #setChunkLifecycle(Consumer, Consumer)} + * @throws FalcoInstanceException if this instance cannot drive the lifecycle of that chunk */ @Override public void unloadChunk(Chunk chunk) { - if (!chunk.isLoaded()) return; - final DynamicChunk falcoChunk = requireManagedChunk(chunk); - final int chunkX = falcoChunk.getChunkX(); - final int chunkZ = falcoChunk.getChunkZ(); - final long index = CoordConversion.chunkIndex(chunkX, chunkZ); - final AtomicBoolean removed = new AtomicBoolean(); - this.loadingChunks.compute(index, (_, running) -> { - if (this.chunks.remove(index, falcoChunk)) { - notifyUnloaded(falcoChunk); - MinecraftServer.process().dispatcher().deletePartition(falcoChunk); - removed.set(true); - } - return running; - }); - if (!removed.get()) return; - falcoChunk.sendPacketToViewers(new UnloadChunkPacket(chunkX, chunkZ)); - EventDispatcher.call(new InstanceChunkUnloadEvent(this, falcoChunk)); - getEntityTracker().chunkEntities(chunkX, chunkZ, EntityTracker.Target.ENTITIES).forEach(Entity::remove); - this.chunkLoader.unloadChunk(falcoChunk); + this.lifecycle.unload(chunk); } @Override public @Nullable Chunk getChunk(int chunkX, int chunkZ) { - return this.chunks.get(CoordConversion.chunkIndex(chunkX, chunkZ)); + return this.registry.chunk(chunkX, chunkZ); } @Override public @UnmodifiableView Collection getChunks() { - return Collections.unmodifiableCollection(this.chunks.values()); + return this.registry.chunks(); } @Override public CompletableFuture saveInstance() { - final ChunkLoader loader = this.chunkLoader; - return runSave(loader.supportsParallelSaving(), () -> loader.saveInstance(this)); + return this.persistence.saveInstance(this); } @Override public CompletableFuture saveChunkToStorage(Chunk chunk) { - final ChunkLoader loader = this.chunkLoader; - return runSave(loader.supportsParallelSaving(), () -> loader.saveChunk(chunk)); + return this.persistence.saveChunk(chunk); } @Override public CompletableFuture saveChunksToStorage() { - final ChunkLoader loader = this.chunkLoader; - final List snapshot = List.copyOf(this.chunks.values()); - return runSave(loader.supportsParallelSaving(), () -> loader.saveChunks(snapshot)); - } - - /** - * Runs a save either on the calling thread or on a virtual thread. - * - * @param parallel true to move the work off the calling thread - * @param save the work to perform - * @return a future completed once the work is done, completed exceptionally if it threw - */ - private CompletableFuture runSave(boolean parallel, Runnable save) { - if (!parallel) { - try { - save.run(); - return CompletableFuture.completedFuture(null); - } catch (Throwable throwable) { - return CompletableFuture.failedFuture(throwable); - } - } - final CompletableFuture future = new CompletableFuture<>(); - Thread.startVirtualThread(() -> { - try { - save.run(); - future.complete(null); - } catch (Throwable throwable) { - future.completeExceptionally(throwable); - } - }); - return future; + return this.persistence.saveChunks(this.registry.snapshot()); } @Override public void setChunkSupplier(ChunkSupplier chunkSupplier) { - this.chunkSupplier = Objects.requireNonNull(chunkSupplier, "the chunk supplier cannot be null"); + this.lifecycle.supplier(chunkSupplier); } @Override public ChunkSupplier getChunkSupplier() { - return this.chunkSupplier; + return this.lifecycle.supplier(); } /** @@ -1173,8 +728,8 @@ public FalcoInstance register(InstanceManager instanceManager) { instance.setChunkLifecycle(this.chunkLoaded, this.chunkUnloaded); } instance.enableAutoChunkLoad(this.autoChunkLoad); - instance.saveOnShutdown = this.saveOnShutdown; - instance.ownsLoader = this.ownsLoader; + instance.persistence.saveOnShutdown(this.saveOnShutdown); + instance.persistence.ownsLoader(this.ownsLoader); instanceManager.registerInstance(instance); return instance; @@ -1208,22 +763,38 @@ public FalcoInstance registerAndShutdownWith(InstanceManager instanceManager, * Without this the instance manages {@link FalcoChunk} and nothing else, for a reason that is * not a preference: {@code Chunk#onLoad()} and {@code Chunk#unload()} are {@code protected}, so * this package can drive them only on a type it defines itself. A caller who owns another chunk - * type can reach both hooks and connects them here — which is how a chunk from another module, - * a lighting chunk for instance, becomes usable in this instance without either module having - * to know the other. + * type can reach both hooks — the type is theirs, so the {@code protected} pair is in reach of + * its own package — and connects them here, without either module having to know the other. *

* 
{@code
-     * instance.setChunkSupplier(scheduler.supplier());
+     * instance.setChunkSupplier(MyChunk::new);
      * instance.setChunkLifecycle(
-     *         chunk -> ((FalcoLightingChunk) chunk).markLoaded(),
-     *         chunk -> ((FalcoLightingChunk) chunk).markUnloaded());
+     *         chunk -> ((MyChunk) chunk).markLoaded(),
+     *         chunk -> ((MyChunk) chunk).markUnloaded());
      * }
*

+ * The lighting chunk of {@code falco-light} used to be the worked example here and is one no + * longer: since US-3.06 {@code FalcoLightingChunk} extends {@link FalcoChunk}, so + * {@code instance.setChunkSupplier(scheduler.supplier())} is the whole setup and this method has + * nothing left to do for it. What remains for this pair is the case it was always the general + * answer to — a chunk type this repository never sees. + *

+ *

* Both halves are one call so the pair cannot be set half way. Set them before the first chunk * is loaded; a chunk that was published under one lifecycle is not told about a later change. * The instance stops checking for {@link FalcoChunk} from here on and requires only a - * {@code DynamicChunk}, so an unsuitable supplier now fails on the cast inside your own - * function rather than with a message from this class. + * {@link Chunk}, so an unsuitable supplier now fails on the cast inside your own function rather + * than with a message from this class. + *

+ *

+ * The two halves are not called under the same conditions, and the difference matters for what + * may be written into them. The loaded half runs after the position of the chunk was released and + * is unconstrained. The unloaded half runs while the position is held, because clearing + * the loaded flag has to be atomic with the chunk leaving the chunk map, so it runs under the + * rules {@link ChunkRegistry} states for such a step: it has to be short, must not block, must + * not call back into the chunk map of this instance — a {@code getChunk}, {@code loadChunk} or + * {@code unloadChunk} from in there can wedge that position for good — and must not throw, which + * would leave the chunk out of the map and only half unloaded. *

* * @param onLoaded what tells a chunk that it is part of this instance @@ -1231,10 +802,7 @@ public FalcoInstance registerAndShutdownWith(InstanceManager instanceManager, * @throws NullPointerException if either half is null */ public void setChunkLifecycle(Consumer onLoaded, Consumer onUnloaded) { - Objects.requireNonNull(onLoaded, "the loaded half of the lifecycle cannot be null"); - Objects.requireNonNull(onUnloaded, "the unloaded half of the lifecycle cannot be null"); - this.chunkLoaded = onLoaded; - this.chunkUnloaded = onUnloaded; + this.lifecycle.hooks(onLoaded, onUnloaded); } /** @@ -1243,7 +811,7 @@ public void setChunkLifecycle(Consumer onLoaded, Consumer onUnload * @return the current chunk loader */ public ChunkLoader getChunkLoader() { - return this.chunkLoader; + return this.persistence.loader(); } /** @@ -1257,7 +825,7 @@ public ChunkLoader getChunkLoader() { * @param chunkLoader the new chunk loader */ public void setChunkLoader(ChunkLoader chunkLoader) { - this.chunkLoader = Objects.requireNonNull(chunkLoader, "the chunk loader cannot be null"); + this.persistence.loader(chunkLoader); } /** @@ -1267,7 +835,7 @@ public void setChunkLoader(ChunkLoader chunkLoader) { */ @Override public @Nullable Generator generator() { - return this.generator; + return this.lifecycle.generation().generator(); } /** @@ -1282,7 +850,7 @@ public void setChunkLoader(ChunkLoader chunkLoader) { */ @Override public void setGenerator(@Nullable Generator generator) { - this.generator = generator; + this.lifecycle.generation().generator(generator); } /** @@ -1312,7 +880,8 @@ public CompletableFuture generateChunk(int chunkX, int chunkZ, Generator g throw new FalcoInstanceException("the chunk " + chunkX + ":" + chunkZ + " was unloaded before the generator could run over it"); } - applyGenerator(chunk, generator); + this.lifecycle.generation().apply(chunk, generator); + refreshLastBlockChangeTime(); chunk.sendChunk(); future.complete(null); } catch (Throwable throwable) { @@ -1322,175 +891,14 @@ public CompletableFuture generateChunk(int chunkX, int chunkZ, Generator g return future; } - /** - * Runs a generator over a chunk and commits everything it produced in one step. - *

- * The generator writes into copies of the palettes of the chunk, not into the palettes - * themselves, and the copies are moved over only after the generator returned. That is the whole - * difference to {@code InstanceContainer#generateChunk(Chunk, Generator)}, which hands the live - * palettes over and catches whatever the generator throws into the exception manager of the - * server. A generator which fails halfway there leaves a chunk that is half built, published and - * reported as loaded, and the caller who asked for the chunk is told nothing. Here the failure - * travels to that caller and the chunk is exactly as it was. - *

- *

- * The copies cost one palette clone per section. On a chunk which is still empty — the case - * which matters, because that is where a generator normally runs — a palette is in its single - * value mode and holds no array at all, so the clone is a few bytes. - *

- *

- * The write lock of the chunk is held for the commit only. Minestom holds it across the whole - * generator instead, which stops every read and every write of that chunk for as long as the - * generator runs. - *

- * - * @param chunk the chunk to fill - * @param generator the generator to run over the chunk - */ - private void applyGenerator(Chunk chunk, Generator generator) { - final List
sections = chunk.getSections(); - final int sectionCount = sections.size(); - final GeneratorImpl.GenSection[] staged = new GeneratorImpl.GenSection[sectionCount]; - Arrays.setAll(staged, index -> { - final Section section = sections.get(index); - return new GeneratorImpl.GenSection(section.blockPalette().clone(), section.biomePalette().clone()); - }); - final GeneratorImpl.UnitImpl unit = GeneratorImpl.chunk(this.registries.biome(), staged, - chunk.getChunkX(), chunk.getMinSection(), chunk.getChunkZ()); - - generator.generate(unit); - - chunk.lockWriteLock(); - try { - for (int index = 0; index < sectionCount; index++) { - final Section section = sections.get(index); - final GeneratorImpl.GenSection generated = staged[index]; - section.blockPalette().copyFrom(generated.blocks()); - section.biomePalette().copyFrom(generated.biomes()); - writeSpecialBlocks(chunk, generated.specials(), - (chunk.getMinSection() + index) * Chunk.CHUNK_SECTION_SIZE); - } - chunk.invalidate(); - } finally { - chunk.unlockWriteLock(); - } - - applyForks(chunk, unit); - applyPendingForks(chunk); - refreshLastBlockChangeTime(); - } - - /** - * Writes the blocks of a generated section which need more than a palette entry. - *

- * A palette holds a block state and nothing else, so a block which carries nbt, a handler or a - * block entity has to be written through the chunk as well. The generator collected those - * separately, keyed by a position relative to its section. - *

- *

- * The caller has to hold the write lock of the chunk. - *

- * - * @param chunk the chunk which receives the blocks - * @param specials the blocks of the section which need their own entry - * @param sectionStartY the block Y at which the section begins - */ - private void writeSpecialBlocks(Chunk chunk, Int2ObjectMap specials, int sectionStartY) { - if (specials.isEmpty()) return; - for (Int2ObjectMap.Entry entry : specials.int2ObjectEntrySet()) { - final int position = entry.getIntKey(); - chunk.setBlock(CoordConversion.chunkBlockIndexGetX(position), - CoordConversion.chunkBlockIndexGetY(position) + sectionStartY, - CoordConversion.chunkBlockIndexGetZ(position), - entry.getValue()); - } - } - - /** - * Delivers the writes a generator made outside the chunk it was asked about. - *

- * A fork which lands in a chunk that exists is applied right away, and one which lands in a - * chunk that does not is remembered until that chunk is created. Dropping the second kind is - * what would make a generator produce a different world depending on the order in which chunks - * were requested, which is the property a fork exists to avoid. - *

- * - * @param chunk the chunk the generator was asked about - * @param unit the unit the generator wrote into - */ - private void applyForks(Chunk chunk, GeneratorImpl.UnitImpl unit) { - final int chunkX = chunk.getChunkX(); - final int chunkZ = chunk.getChunkZ(); - for (GeneratorImpl.UnitImpl fork : unit.forks()) { - if (!(fork.modifier() instanceof GeneratorImpl.AreaModifierImpl area)) continue; - for (GenerationUnit section : area.sections()) { - if (!(section.modifier() instanceof GeneratorImpl.SectionModifierImpl modifier)) continue; - if (modifier.genSection().blocks().count() == 0) continue; - final Point start = section.absoluteStart(); - if (start.chunkX() == chunkX && start.chunkZ() == chunkZ) { - applyFork(chunk, modifier); - continue; - } - final Chunk target = getChunkAt(start); - if (target != null && target.isLoaded()) { - applyFork(target, modifier); - target.sendChunk(); - continue; - } - this.generationForks.compute(CoordConversion.chunkIndex(start), (_, modifiers) -> { - final List pending = - modifiers == null ? new ArrayList<>() : modifiers; - pending.add(modifier); - return pending; - }); - } - } - } - - /** - * Applies the forks which were waiting for the given chunk to exist. - * - * @param chunk the chunk which just came into being - */ - private void applyPendingForks(Chunk chunk) { - final long index = CoordConversion.chunkIndex(chunk.getChunkX(), chunk.getChunkZ()); - this.generationForks.compute(index, (_, modifiers) -> { - if (modifiers != null) { - for (GeneratorImpl.SectionModifierImpl modifier : modifiers) applyFork(chunk, modifier); - } - return null; - }); - } - - /** - * Writes one section of a fork into a chunk. - * - * @param chunk the chunk which receives the blocks - * @param modifier the section of the fork to write - */ - private void applyFork(Chunk chunk, GeneratorImpl.SectionModifierImpl modifier) { - final int sectionStartY = modifier.start().blockY(); - chunk.lockWriteLock(); - try { - final Palette blocks = chunk.getSectionAt(sectionStartY).blockPalette(); - // A forked section marks an untouched position with a zero, so every block it does carry - // was stored with its state raised by one and has to be lowered again here. - modifier.genSection().blocks().getAllPresent((x, y, z, value) -> blocks.set(x, y, z, value - 1)); - writeSpecialBlocks(chunk, modifier.genSection().specials(), sectionStartY); - chunk.invalidate(); - } finally { - chunk.unlockWriteLock(); - } - } - @Override public void enableAutoChunkLoad(boolean enable) { - this.autoChunkLoad = enable; + this.lifecycle.autoLoad(enable); } @Override public boolean hasEnabledAutoChunkLoad() { - return this.autoChunkLoad; + return this.lifecycle.autoLoad(); } @Override @@ -1509,7 +917,7 @@ public boolean isInVoid(Point point) { * @return the time of the last block change in nanoseconds */ public long getLastBlockChangeTime() { - return this.lastBlockChangeTime; + return this.blockWriter.lastChangeTime(); } /** @@ -1519,14 +927,14 @@ public long getLastBlockChangeTime() { *

*/ public void refreshLastBlockChangeTime() { - this.lastBlockChangeTime = System.nanoTime(); + this.blockWriter.refreshLastChangeTime(); } /** * Runs one tick of this instance. *

- * Beyond what the base class does, this clears the recursion guard of the block writes, which - * is scoped to a single tick. + * Beyond what the base class does, this ends the tick of {@link BlockWriter}, which clears the + * recursion guard of the block writes; the guard is scoped to a single tick. *

*

* Chunks and entities are not ticked here. They are ticked by the thread dispatcher of the @@ -1538,6 +946,6 @@ public void refreshLastBlockChangeTime() { @Override public void tick(long time) { super.tick(time); - this.currentlyChangingBlocks.clear(); + this.blockWriter.endTick(); } } diff --git a/falco-instance/src/main/java/net/onelitefeather/falco/instance/LazySectionBlockStorage.java b/falco-instance/src/main/java/net/onelitefeather/falco/instance/LazySectionBlockStorage.java new file mode 100644 index 0000000..e5842bb --- /dev/null +++ b/falco-instance/src/main/java/net/onelitefeather/falco/instance/LazySectionBlockStorage.java @@ -0,0 +1,389 @@ +package net.onelitefeather.falco.instance; + +import net.minestom.server.MinecraftServer; +import net.minestom.server.coordinate.CoordConversion; +import net.minestom.server.instance.Section; +import net.minestom.server.instance.block.Block; +import net.minestom.server.registry.DynamicRegistry; +import net.minestom.server.registry.RegistryKey; +import net.minestom.server.utils.validate.Check; +import net.minestom.server.world.biome.Biome; +import org.jetbrains.annotations.ApiStatus; + +import java.lang.invoke.MethodHandles; +import java.lang.invoke.VarHandle; +import java.util.AbstractList; +import java.util.Arrays; +import java.util.List; +import java.util.Objects; + +/** + * The {@link LazySectionBlockStorage} class stores the blocks of a chunk in Minestom {@link Section} + * objects again, but allocates one only for a section that holds something: every section which is + * nothing but air points at one shared instance which no chunk owns and none writes to. + *

+ * This is the layout the whole design was built for, and the reason it can exist at all is that + * stage 1 moved the storage out of the chunk. The pattern fits nowhere else. {@code Section} is a + * {@code record} and therefore final, and {@code Palette} is declared + * {@code public sealed interface Palette permits PaletteImpl}, so neither a lazy section nor a lazy + * palette can be handed to Minestom — the sharing has to live one level above both, which is exactly + * where {@link BlockStorage} sits. + *

+ *

+ * What it is worth was counted rather than assumed. A generated overworld holds {@code 62,24 %} of + * the sections of its finished chunks as pure air, over four hundred and forty one chunks around one + * spawn, and at that share the layout saves {@code 2 911} bytes per chunk. Constructing a chunk this + * way allocates {@code 2 104} against {@code 7 096} bytes. Both figures come from + * {@code EmptySectionCensusTest} and {@code LazySectionBenchmark} in {@code falco-benchmarks} and + * carry the conditions stated there; neither is a projection. + *

+ * + *

Why a first write allocates instead of cloning the shared section

+ *

+ * The obvious copy on write step is {@code EMPTY.clone()} and it is the wrong one. + * {@code Section#clone} creates two fresh light carriers and then calls + * {@code skyLight.set(this.skyLight.array())} on them. For the shared section {@code array()} answers + * with {@code LightCompute.UNSET_CONTENT}, a zero length array, and {@code SkyLight#set} turns that + * into {@code LightCompute.EMPTY_CONTENT} — the process wide, mutable {@code byte[2048]} — while + * also setting {@code isValidBorders} and raising {@code needsSend}. A section materialised that way + * would announce that it has light to send before anything ever lit it, and would hold its + * {@code content} field pointing at an array shared with every other section built the same way. + * {@code new Section()} produces the same blocks, leaves the light unset and allocates less, which is + * what {@code LazySectionBenchmark#firstWriteLazy} measured at {@code 2 720 B/op}. + *

+ * + *

What is shared, and the one rule that keeps it safe

+ *

+ * {@link #EMPTY} is never written to by this class. Every write path replaces the slot first, and the + * two accessors that can hand the shared section to a caller — {@link #view(int)} and + * {@link #views()} — document in {@link BlockStorage} that their result is read only. The accessors + * Minestom itself reaches, {@link #section(int)} and {@link #sections()}, materialise instead, because + * a chunk loader or the generator of an {@code InstanceContainer} receives a {@code Section} through + * them and writes into its palettes directly. That is the honest price of this layout and it is + * stated rather than hidden: any caller of {@code Chunk#getSections()} makes this storage as + * expensive as the eager one. + *

+ *

+ * A write of the state the shared section already holds everywhere is skipped rather than + * materialised. That is not an optimisation of a rare case: a loader or a generator which walks a + * whole chunk and writes air into the parts that are air would otherwise materialise every section it + * touched and this class would be strictly worse than the eager one. The check is on the state id and + * not on {@code Block#isAir()}, because cave air and void air are air by that predicate and are + * different states which have to be stored. + *

+ * + *

The one step that cannot rely on the chunk lock

+ *

+ * Implementations of {@link BlockStorage} are not thread-safe and this one is no exception: two + * writers into the same palette race here exactly as they race in {@code DynamicChunk}, and the write + * lock of the chunk is what keeps them apart. Materialising a slot is the one step that cannot be + * left to that lock, because the boundary this class sits behind is reachable without it. + * {@code Chunk#getSection(int)} and {@code Chunk#getSectionAt(int)} end in {@link #section(int)}, and + * three inherited methods of {@code Instance} reach them holding no chunk lock at all — + * {@code Instance#getBlockLight}, {@code Instance#getSkyLight} and + * {@code Instance#invalidateSection}, each of which takes a section before it has decided what kind + * of chunk it is looking at. + *

+ *

+ * A read of the slot, an allocation and a plain store would therefore lose blocks. A writer holding + * the write lock materialises a slot and writes stone into its palette; a light query on another + * thread read the same slot before that store, saw {@link #EMPTY}, allocates its own section and + * stores it over the first one. The stone is gone with no exception and no log, and the next read + * answers air through the shortcut in {@link #getBlock}. {@code DynamicChunk} cannot have this race, + * because its section list is final and complete from construction; it exists here only because a + * slot can change at all. + *

+ *

+ * A slot is therefore published with {@link VarHandle#compareAndExchange}: the loser of a race drops + * the section it allocated and answers with the winner's, so every caller of a slot ends up with the + * same section and no store is ever lost. Taking the write lock inside {@link #section(int)} would + * not do it and is not a matter of taste — {@code Heightmap#refresh(int)} holds the read + * lock of the chunk while it walks its columns through {@code Chunk#getSection(int)}, and + * {@code Chunk#lockWriteLock} asserts that its caller holds no read lock. What this costs when + * nothing races is one acquiring read of a slot, and a compare and exchange only on the step which + * was going to allocate a section anyway. + *

+ * + * @author TheMeinerLP + * @version 1.1.0 + * @since 0.4.0 + */ +@ApiStatus.Experimental +public final class LazySectionBlockStorage implements BlockStorage { + + /** + * The section every empty slot of every chunk of this process points at. + *

+ * It is never written to. Every write path of this class replaces the slot before it writes, and + * the two read-only accessors document that a caller must not write through what they return. A + * write that reached this object would not corrupt one chunk, it would corrupt every chunk whose + * slot at that height happens to be empty. + *

+ */ + static final Section EMPTY = new Section(); + + /** + * The state id a write has to carry to be worth materialising a shared section for. + *

+ * Read from the registry rather than written down as {@code 0}, so that a Minecraft version which + * renumbered the states cannot silently turn this guard into one that drops real blocks. + *

+ */ + private static final int AIR_STATE = Block.AIR.stateId(); + + /** + * The edge length of the biome grid of a section. + *

+ * Named here for the same reason {@code SectionBlockStorage} names it: {@code Section} has no + * constant for it, and a wrong biome divisor is silent rather than loud. + *

+ */ + private static final int BIOME_SIZE = 4; + + private static final DynamicRegistry BIOME_REGISTRY = MinecraftServer.getBiomeRegistry(); + + /** + * The handle every read and every write of a slot of {@link #sections} goes through. + *

+ * A {@code VarHandle} over the array rather than an {@code AtomicReferenceArray} because the two + * differ in what they cost: the atomic array is an object plus a second array per storage, which + * is a post {@code ChunkFootprintTest} would have to declare and every chunk would pay, while a + * static handle over the array this class already holds costs nothing per storage and leaves the + * single threaded read a plain load on every architecture this runs on. + *

+ */ + private static final VarHandle SLOT = MethodHandles.arrayElementVarHandle(Section[].class); + + private final int minSection; + private final Section[] sections; + + /** + * The list {@link #views()} answers with. + *

+ * It reads through to {@link #sections} rather than copying it, which is what lets a caller take + * it once and still see a section that was materialised afterwards. It is also why {@link #views()} + * allocates nothing: the chunk packet builder walks this list on every send, and a list built per + * send would be a cost this class was written to remove rather than to add. + *

+ */ + private final List
view = new AbstractList<>() { + + @Override + public Section get(int index) { + return LazySectionBlockStorage.this.slot(index); + } + + @Override + public int size() { + return LazySectionBlockStorage.this.sections.length; + } + }; + + /** + * Creates a storage in which every section is shared. + * + * @param minSection the index of the bottom section of the chunk + * @param sectionCount the amount of sections the chunk spans + */ + public LazySectionBlockStorage(int minSection, int sectionCount) { + this.minSection = minSection; + this.sections = new Section[sectionCount]; + Arrays.fill(this.sections, EMPTY); + } + + /** + * Creates a storage which takes over the given sections. + *

+ * A section which is identical to the shared one is not detected here and is taken over as it + * stands. Deciding otherwise would mean walking four thousand and ninety six positions per + * section to find out, which is more than the slot is worth; a caller which knows that a section + * is empty passes {@link #EMPTY} for it. + *

+ * + * @param minSection the index of the bottom section of the chunk + * @param sections the sections, from the bottom one upwards + */ + public LazySectionBlockStorage(int minSection, List
sections) { + this.minSection = minSection; + this.sections = sections.toArray(new Section[0]); + } + + /** + * Creates a storage over an array this class takes ownership of. + * + * @param minSection the index of the bottom section of the chunk + * @param sections the sections, from the bottom one upwards + */ + private LazySectionBlockStorage(int minSection, Section[] sections) { + this.minSection = minSection; + this.sections = sections; + } + + @Override + public Block getBlock(int x, int y, int z, Block.Getter.Condition condition) { + final Section section = slot(CoordConversion.globalToChunk(y) - this.minSection); + + // US-2.07: a shared section is air everywhere, so the palette is not reached at all. The + // palette of the shared section would answer the same; this is a shortcut, not a special case. + if (section == EMPTY) { + return Block.AIR; + } + final int stateId = section.blockPalette() + .get(x, CoordConversion.globalToSectionRelative(y), z); + + return Objects.requireNonNullElse(Block.fromStateId(stateId), Block.AIR); + } + + @Override + public void setBlock(int x, int y, int z, Block block) { + final int index = CoordConversion.globalToChunk(y) - this.minSection; + final int stateId = block.stateId(); + + if (stateId == AIR_STATE && slot(index) == EMPTY) { + return; + } + materialise(index).blockPalette() + .set(x, CoordConversion.globalToSectionRelative(y), z, stateId); + } + + @Override + public RegistryKey getBiome(int x, int y, int z) { + final Section section = slot(CoordConversion.globalToChunk(y) - this.minSection); + final int id = section.biomePalette() + .get(x / BIOME_SIZE, + CoordConversion.globalToSectionRelative(y) / BIOME_SIZE, + z / BIOME_SIZE); + + final RegistryKey biome = BIOME_REGISTRY.getKey(id); + + Check.notNull(biome, "Biome with id {0} is not registered", id); + return biome; + } + + @Override + public void setBiome(int x, int y, int z, RegistryKey biome) { + final int id = BIOME_REGISTRY.getId(biome); + + if (id == -1) throw new IllegalStateException("Biome has not been registered: " + biome.key()); + + final int index = CoordConversion.globalToChunk(y) - this.minSection; + + // Unlike a block write, a biome write is not skipped when it matches what the shared section + // holds. The zero of a biome palette is a registry id and not a sentinel, so the id which + // happens to be zero belongs to a real biome that a caller may legitimately want stored, and + // it is not this class's business to decide that writing it is a no-op. + materialise(index).biomePalette() + .set(x / BIOME_SIZE, + CoordConversion.globalToSectionRelative(y) / BIOME_SIZE, + z / BIOME_SIZE, id); + } + + @Override + public List
sections() { + for (int index = 0; index < this.sections.length; index++) { + materialise(index); + } + return this.view; + } + + @Override + public Section section(int section) { + return materialise(section); + } + + @Override + public Section view(int section) { + return slot(section); + } + + @Override + public List
views() { + return this.view; + } + + @Override + public boolean shared(int section) { + return slot(section) == EMPTY; + } + + @Override + public int materialisedSections() { + int owned = 0; + + for (int index = 0; index < this.sections.length; index++) { + if (slot(index) != EMPTY) owned++; + } + return owned; + } + + @Override + public int sectionCount() { + return this.sections.length; + } + + @Override + public BlockStorage copy() { + final Section[] copied = new Section[this.sections.length]; + + for (int index = 0; index < copied.length; index++) { + final Section section = slot(index); + copied[index] = section == EMPTY ? EMPTY : section.clone(); + } + return new LazySectionBlockStorage(this.minSection, copied); + } + + @Override + public void clear() { + for (int index = 0; index < this.sections.length; index++) { + final Section section = slot(index); + + if (section == EMPTY) continue; + // Emptied as well as released. A caller which took the section through the boundary + // before the reset holds a reference this class cannot reach, and DynamicChunk#reset + // leaves such a caller with an emptied section rather than with a stale one. + section.clear(); + // Released with the same handle the materialisation publishes through, so that a + // materialisation racing this reset either sees the slot before it was released and + // keeps its section, or sees it afterwards and materialises a new one. A plain store + // here would leave that compare and exchange comparing against a value it cannot be + // ordered against. + SLOT.setRelease(this.sections, index, EMPTY); + } + } + + /** + * Reads what a slot currently holds. + * + * @param index the index of the section, counted from the bottom one + * @return the section the slot holds, which may be the shared one + */ + private Section slot(int index) { + return (Section) SLOT.getAcquire(this.sections, index); + } + + /** + * Gives a slot a section of its own, if it does not have one yet. + *

+ * The store is a compare and exchange rather than an assignment, and the section this method + * answers with is the one that ended up in the slot rather than the one it happens to have + * allocated. Both halves of that matter: the first is what stops a caller without the chunk lock + * from overwriting a section somebody else already wrote a block into, and the second is what + * stops the loser of such a race from writing into a section no slot holds. The section the loser + * allocated is garbage by the time it returns, which is the whole price of the race and is paid + * only when there is one. + *

+ * + * @param index the index of the section, counted from the bottom one + * @return the section the slot holds afterwards, which this storage owns + */ + private Section materialise(int index) { + final Section section = slot(index); + + if (section != EMPTY) return section; + + final Section created = new Section(); + final Section witness = (Section) SLOT.compareAndExchange(this.sections, index, EMPTY, created); + + return witness == EMPTY ? created : witness; + } +} diff --git a/falco-instance/src/main/java/net/onelitefeather/falco/instance/PaletteCompaction.java b/falco-instance/src/main/java/net/onelitefeather/falco/instance/PaletteCompaction.java new file mode 100644 index 0000000..4b3699b --- /dev/null +++ b/falco-instance/src/main/java/net/onelitefeather/falco/instance/PaletteCompaction.java @@ -0,0 +1,212 @@ +package net.onelitefeather.falco.instance; + +import it.unimi.dsi.fastutil.ints.IntOpenHashSet; +import it.unimi.dsi.fastutil.ints.IntSet; +import net.minestom.server.instance.palette.Palette; +import org.jetbrains.annotations.ApiStatus; + +/** + * The {@link PaletteCompaction} class decides whether {@code Palette#optimize(Optimization.SIZE)} can + * still narrow a palette before that call is made. + *

+ * {@code optimize} is not a cheap call and it is not a call that reports whether it achieved anything. + * {@code PaletteImpl#optimize} first walks all entries of the palette through {@code getAll} and + * collects the distinct values into a hash set, and only then does + * {@code PaletteImpl#downsizeWithPalette} decide, on its opening + * {@code if (newBpe >= bpe || newBpe > maxBitsPerEntry) return;}, that the width the content needs is + * not one it can store. The walk is the expensive half and it is paid either way. + * {@code GeneratorCommitBenchmark} measured it on a chunk of twenty-four sections: {@code 576,7 µs} + * against {@code 22,0 µs} for the bare commit at sixty-four distinct states, where the palettes went + * from fifteen bits to six, and {@code 529,8 µs} against {@code 26,3 µs} at one thousand and + * twenty-four distinct states, where they stayed at fifteen. The second figure is the whole reason + * this class exists: half a millisecond of a chunk generation for zero bytes. + *

+ * + *

What can be decided without doing the work

+ *

+ * Nothing on the {@link Palette} interface reports how many distinct values a palette holds. + * {@code count()} answers how many entries are not air, which is a different question, and the palette + * list that would answer it exists only in the indirect mode and is not exposed. The number therefore + * has to be found by looking at entries — but not at all of them, and that is the difference between + * this class and the call it guards. A palette narrows only if its distinct count is small, so a + * bound on the count is enough to rule the narrowing out, and a bound is reached as soon as + * enough distinct values have been seen. The probe below reads a fixed sample of positions and stops + * at the first value that puts the count past what {@code downsizeWithPalette} could store. + *

+ *

+ * That makes the answer one-sided on purpose. A {@code false} is a proof — the palette provably holds + * more distinct values than the mode below it can index, so {@code optimize} would walk everything and + * return unchanged. A {@code true} is not a promise that anything will be gained; it only says that + * the sample gave no reason to skip. Being wrong in that direction costs the call that would have + * happened anyway, while being wrong in the other direction would silently leave chunks at the direct + * width, which is what this whole stage is trying to avoid. The sample is bounded rather than complete + * so that the guard cannot become as expensive as the call it is guarding. + *

+ * + *

The threshold

+ *

+ * {@code optimize} does something in exactly two cases. One distinct value goes to {@code fill} and + * collapses the palette into the single value mode, whatever its width was. Anything else goes to + * {@code downsizeWithPalette}, which computes + * {@code newBpe = max(bitsToRepresent(distinct - 1), minBitsPerEntry)} and returns unchanged unless + * that width is both smaller than the current one and no larger than {@code maxBitsPerEntry}. Writing + * {@code reachable = min(bitsPerEntry, maxBitsPerEntry + 1)} for the width a narrowing has to beat, + * the second case therefore needs {@code minBitsPerEntry < reachable} and + * {@code distinct <= 2^(reachable - 1)}. For a block palette at the direct width that is + * {@code 2^8 = 256} distinct states; for one already at the minimum of four bits it is {@code 1}, so + * two distinct values are enough to prove that only the {@code fill} case could still apply and it + * cannot. + *

+ * + *

What the guard is worth, and what it costs

+ *

+ * Measured by {@code GeneratorCommitBenchmark} over a chunk of twenty-four sections, all of them at + * the width a generator leaves, in microseconds per commit of the whole chunk: + *

+ * 
{@code
+ * distinct states per section            1        64      1024
+ * commit only                        0,044    22,045    26,254
+ * commit + optimize                  0,049   576,655   529,768
+ * commit + this guard                0,049   713,962   185,081
+ * optimize an already packed chunk   0,047   270,642   535,028
+ * this guard on the same chunk       0,047    31,799   176,137
+ * }
+ *

+ * Three readings, and the third one is the price rather than the gain. A chunk whose palettes are + * already as narrow as their content allows — what every commit onto content that a loader or an + * earlier generation produced is handed — costs {@code 270,6 µs} to find that out and {@code 31,8 µs} + * to be told in advance, a factor of {@code 8,5}. A chunk past the indirect ceiling costs + * {@code 529,8 µs} against {@code 185,1 µs}, a factor of {@code 2,9}. And a chunk the optimisation can + * genuinely narrow costs {@code 137 µs} more than it would without the guard, because the probe walks + * its whole sample before it lets the call through: {@code 714,0 µs} against {@code 576,7 µs}, which is + * {@code 24 %} on the one case where the work was worth doing. The sections of a real chunk that carry + * a single state pay none of this, since the guard returns on the same {@code bitsPerEntry == 0} the + * optimisation returns on. + *

+ *

+ * Conditions: Ryzen 7 5800X, sixteen threads, JDK 25.0.3, JMH with three forks, five warmup and five + * measurement iterations of one second each, fifteen samples per point, {@code -prof gc}. The machine + * was not idle — load average between {@code 4,4} and {@code 6,8} — so the absolute + * values carry more noise than the ratios between arms of the same run do, and the {@code ± 42 µs} on + * the sixty-four state arm is real. + *

+ *

+ * This type is internal. It states a property of {@code PaletteImpl} that the {@link Palette} + * interface does not promise, so it belongs to the commit path of this module and not to its API, and + * it is worth nothing to anyone who is not about to call {@code optimize}. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ApiStatus.Internal +@ApiStatus.Experimental +public final class PaletteCompaction { + + /** + * How many positions the probe reads before it gives up and lets {@code optimize} run. + *

+ * A block palette holds {@code 4096} entries, so this is one eighth of one. It has to be larger + * than the largest threshold the rule below can produce — {@code 256} for a block palette — because + * a probe that cannot reach the threshold can never skip anything, and it has to stay far enough + * below the full count that the guard remains cheap next to the walk it replaces. + *

+ */ + private static final int PROBE_SAMPLES = 512; + + /** + * The stride the probe walks the entry indices with. + *

+ * Any odd number is coprime with the entry count of a palette, which is a power of two, so a stride + * of nine visits {@link #PROBE_SAMPLES} distinct positions and spreads them over every x, y and z + * of the section rather than over one plane of it. A stride of eight — the obvious one for a + * sample of one eighth — would read two of the sixteen x values and nothing else. + *

+ */ + private static final int PROBE_STRIDE = 9; + + private PaletteCompaction() { + } + + /** + * Narrows a block palette to the width its content needs, unless that is provably impossible. + * + * @param palette the block palette to pack + */ + public static void packBlocks(Palette palette) { + pack(palette, Palette.BLOCK_PALETTE_MIN_BITS, Palette.BLOCK_PALETTE_MAX_BITS); + } + + /** + * Narrows a biome palette to the width its content needs, unless that is provably impossible. + *

+ * A biome palette holds sixty-four entries, so the probe reads all of them and the answer is exact + * rather than one-sided. The guard is kept for it anyway, because a palette that cannot narrow is + * the common case for biomes too — a generator usually writes one biome per section — and because + * a rule that holds for one palette and not for the other is a rule nobody can check at a glance. + *

+ * + * @param palette the biome palette to pack + */ + public static void packBiomes(Palette palette) { + pack(palette, Palette.BIOME_PALETTE_MIN_BITS, Palette.BIOME_PALETTE_MAX_BITS); + } + + /** + * Runs {@code Palette#optimize(Optimization.SIZE)} unless {@link #canNarrow(Palette, int, int)} + * has ruled it out. + * + * @param palette the palette to pack + * @param minBitsPerEntry the narrowest indirect width this palette can take + * @param maxBitsPerEntry the widest indirect width this palette can take + */ + static void pack(Palette palette, int minBitsPerEntry, int maxBitsPerEntry) { + if (canNarrow(palette, minBitsPerEntry, maxBitsPerEntry)) { + palette.optimize(Palette.Optimization.SIZE); + } + } + + /** + * Reports whether {@code Palette#optimize(Optimization.SIZE)} could still change this palette. + *

+ * A {@code false} means it provably could not: either the palette is already in the single value + * mode, where {@code optimize} returns on its first line, or the probe has seen more distinct + * values than the widest mode below the current one can index. A {@code true} means the sample + * found no such proof, which is not the same as a saving. + *

+ * + * @param palette the palette to look at, which is read and never written + * @param minBitsPerEntry the narrowest indirect width this palette can take + * @param maxBitsPerEntry the widest indirect width this palette can take + * @return whether the optimisation is still worth attempting + */ + static boolean canNarrow(Palette palette, int minBitsPerEntry, int maxBitsPerEntry) { + final int bitsPerEntry = palette.bitsPerEntry(); + + if (bitsPerEntry == 0) return false; + + final int dimension = palette.dimension(); + + if (Integer.bitCount(dimension) != 1) return true; + + final int reachable = Math.min(bitsPerEntry, maxBitsPerEntry + 1); + final int distinctLimit = minBitsPerEntry < reachable ? 1 << (reachable - 1) : 1; + final int entries = dimension * dimension * dimension; + final int samples = Math.min(entries, PROBE_SAMPLES); + final int shift = Integer.numberOfTrailingZeros(dimension); + final int mask = dimension - 1; + final IntSet distinct = new IntOpenHashSet(); + + for (int sample = 0; sample < samples; sample++) { + final int index = (sample * PROBE_STRIDE) & (entries - 1); + final int x = index & mask; + final int z = (index >> shift) & mask; + final int y = index >> (shift + shift); + final int value = palette.get(x, y, z); + + if (distinct.add(value) && distinct.size() > distinctLimit) return false; + } + return true; + } +} diff --git a/falco-instance/src/main/java/net/onelitefeather/falco/instance/SectionBlockStorage.java b/falco-instance/src/main/java/net/onelitefeather/falco/instance/SectionBlockStorage.java new file mode 100644 index 0000000..8fbcca0 --- /dev/null +++ b/falco-instance/src/main/java/net/onelitefeather/falco/instance/SectionBlockStorage.java @@ -0,0 +1,213 @@ +package net.onelitefeather.falco.instance; + +import net.minestom.server.MinecraftServer; +import net.minestom.server.coordinate.CoordConversion; +import net.minestom.server.instance.Section; +import net.minestom.server.instance.block.Block; +import net.minestom.server.registry.DynamicRegistry; +import net.minestom.server.registry.RegistryKey; +import net.minestom.server.utils.validate.Check; +import net.minestom.server.world.biome.Biome; +import org.jetbrains.annotations.ApiStatus; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; +import java.util.Objects; + +/** + * The {@link SectionBlockStorage} class stores the blocks of a chunk in Minestom {@link Section} + * objects, one per sixteen blocks of height, allocated when the storage is created. + *

+ * This is deliberately the layout {@code DynamicChunk} already has, and it is the first + * implementation on purpose: it makes the bridge measurable before the bridge changes anything. A + * chunk built on this storage has to be indistinguishable from a {@code DynamicChunk} in both time + * and bytes, and {@code ChunkComparisonBenchmark} together with {@code ChunkFootprintTest} is what + * says whether it is. A layout that saves memory is the subject of the next stage; if this one + * already differed, the difference of that next stage could not be attributed to it. + *

+ *

+ * The coordinate arithmetic below is copied from {@code DynamicChunk#getBlock}, + * {@code DynamicChunk#setBlock} and {@code DynamicChunk#getBiome} rather than re-derived, including + * the biome divisor of {@code 4}: {@code Section} has no {@code BIOME_SIZE} constant to name it + * with, and getting a section index or a biome divisor wrong here is silent, not loud, since both + * still return a value, just the wrong one. + *

+ *

+ * What is deliberately not copied is the masking of {@code x} and {@code z}. + * {@code DynamicChunk} receives the instance-level coordinates and has to fold them into its chunk + * itself; {@link BlockStorage} states that the caller has already done that, and this class takes + * the contract at its word. The gain is that a violation is loud: {@code Palette#set} rejects a + * coordinate outside {@code 0} to {@code 15} with an {@code IllegalArgumentException}, whereas a + * mask would have silently folded a block from a neighbouring chunk into this one. + *

+ * + *

The two guards on values a palette cannot check

+ *

+ * A palette holds plain integers, so nothing in it is a block or a biome, and + * {@code Palette#set} validates the coordinates and never the value. Both a state id and a biome id + * can therefore reach a section without ever passing {@link #setBlock} or {@link #setBiome}: + * {@code ChunkGeneration#applyFork} and every chunk loader write through {@code section.blockPalette()} + * directly. {@code DynamicChunk} guards both reads and one of the writes, and both guards are copied + * here rather than re-derived — but they are worth different things, and the difference is stated + * because the block one reads like dead code and is. + *

+ *

+ * The biome guards are live. {@code Registry#getId} answers a lookup miss with {@code -1}, a palette + * stores that like any other value and counts it, and the chunk packet carries it to a client, so a + * write without the check turns a caller error into a corrupt chunk that fails somewhere else + * entirely. {@link #getBiome(int, int, int)} guards the read for the same reason, since a chunk + * loaded from disk can carry an id this server does not know. + *

+ *

+ * The air fallback in {@link #getBlock(int, int, int, Block.Getter.Condition)} is the opposite: with + * Minestom as pinned here it cannot fire. {@code BlockImpl} builds its state table through + * {@code ObjectArray#toList}, which is a {@code List#of} and therefore rejects a null element, so + * every id below {@code Block#statesCount()} is a block and every id at or above it throws out of + * the list before the fallback is reached. It is kept anyway, for one reason that is not + * superstition: {@code Block#fromStateId} is declared {@code @Nullable}, and this method promises a + * block, which is what {@code Block.Getter.Condition#NONE} means. A promise that rests on a fact + * about the current registry rather than on the signature of the method it calls is a promise that + * breaks silently and elsewhere. + *

+ *

+ * The four members that exist for a lazy layout are constant answers in this one. Every section is + * allocated in the constructor, so nothing is ever shared and nothing is ever materialised: a view + * is the section, {@code shared} is always false and {@code materialisedSections} is the section + * count. That is not a stub — it is what makes this class usable as the eager control in every + * comparison of the next stage, and it is why the same interface can describe both layouts without + * either of them carrying a flag about which one it is. + *

+ * + * @author TheMeinerLP + * @version 1.2.1 + * @since 0.4.0 + */ +@ApiStatus.Experimental +public final class SectionBlockStorage implements BlockStorage { + + private static final int BIOME_SIZE = 4; + + private static final DynamicRegistry BIOME_REGISTRY = MinecraftServer.getBiomeRegistry(); + + private final int minSection; + private final List
sections; + + /** + * Creates a storage of empty sections. + * + * @param minSection the index of the bottom section of the chunk + * @param sectionCount the amount of sections the chunk spans + */ + public SectionBlockStorage(int minSection, int sectionCount) { + final Section[] created = new Section[sectionCount]; + + Arrays.setAll(created, index -> new Section()); + this.minSection = minSection; + this.sections = List.of(created); + } + + /** + * Creates a storage which takes over the given sections. + * + * @param minSection the index of the bottom section of the chunk + * @param sections the sections, from the bottom one upwards + */ + public SectionBlockStorage(int minSection, List
sections) { + this.minSection = minSection; + this.sections = List.copyOf(sections); + } + + @Override + public Block getBlock(int x, int y, int z, Block.Getter.Condition condition) { + final Section section = section(CoordConversion.globalToChunk(y) - this.minSection); + final int stateId = section.blockPalette() + .get(x, CoordConversion.globalToSectionRelative(y), z); + + return Objects.requireNonNullElse(Block.fromStateId(stateId), Block.AIR); + } + + @Override + public void setBlock(int x, int y, int z, Block block) { + section(CoordConversion.globalToChunk(y) - this.minSection).blockPalette() + .set(x, CoordConversion.globalToSectionRelative(y), z, block.stateId()); + } + + @Override + public RegistryKey getBiome(int x, int y, int z) { + final Section section = section(CoordConversion.globalToChunk(y) - this.minSection); + final int id = section.biomePalette() + .get(x / BIOME_SIZE, + CoordConversion.globalToSectionRelative(y) / BIOME_SIZE, + z / BIOME_SIZE); + + final RegistryKey biome = BIOME_REGISTRY.getKey(id); + + Check.notNull(biome, "Biome with id {0} is not registered", id); + return biome; + } + + @Override + public void setBiome(int x, int y, int z, RegistryKey biome) { + final int id = BIOME_REGISTRY.getId(biome); + + if (id == -1) throw new IllegalStateException("Biome has not been registered: " + biome.key()); + + section(CoordConversion.globalToChunk(y) - this.minSection).biomePalette() + .set(x / BIOME_SIZE, + CoordConversion.globalToSectionRelative(y) / BIOME_SIZE, + z / BIOME_SIZE, id); + } + + @Override + public List
sections() { + return this.sections; + } + + @Override + public Section section(int section) { + return this.sections.get(section); + } + + @Override + public int sectionCount() { + return this.sections.size(); + } + + @Override + public Section view(int section) { + return section(section); + } + + @Override + public List
views() { + return this.sections; + } + + @Override + public boolean shared(int section) { + return false; + } + + @Override + public int materialisedSections() { + return this.sections.size(); + } + + @Override + public BlockStorage copy() { + final List
copied = new ArrayList<>(this.sections.size()); + + for (Section section : this.sections) { + copied.add(section.clone()); + } + return new SectionBlockStorage(this.minSection, copied); + } + + @Override + public void clear() { + for (Section section : this.sections) { + section.clear(); + } + } +} diff --git a/falco-instance/src/test/java/net/minestom/server/instance/ChunkViewerCacheTest.java b/falco-instance/src/test/java/net/minestom/server/instance/ChunkViewerCacheTest.java new file mode 100644 index 0000000..d3386b0 --- /dev/null +++ b/falco-instance/src/test/java/net/minestom/server/instance/ChunkViewerCacheTest.java @@ -0,0 +1,128 @@ +package net.minestom.server.instance; + +import net.minestom.server.world.DimensionType; +import net.onelitefeather.falco.instance.FalcoInstance; +import net.minestom.testing.Env; +import net.minestom.testing.extension.MicrotusExtension; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; + +import java.util.UUID; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Establishes that a chunk which is unloaded takes its viewer cache entry with it, which is US-3.01. + *

+ * The entry is created by the constructor of {@code Chunk} ({@code Chunk.java:74-76}), which asks the + * entity tracker of the instance for a viewable and gets one out of a + * {@code computeIfAbsent}. Nothing in Minestom ever removes it: not unloading the chunk, not dropping + * the last reference to it, not unregistering the instance. A world which streams chunks in and out + * therefore accumulates one entry per position ever visited, for the life of the process. + *

+ *

+ * This test lives in {@code net.minestom.server.instance} for the same reason the class it tests + * does: the map is package-private and reading it from anywhere else would need reflection. + *

+ * + *

+ * Every case here starts from a freshly registered instance whose cache is empty, which makes a + * single-position case blind in one direction: a {@code release} which wipes the whole map passes it, + * because wiping a map that holds one entry and removing that one entry are the same observation. + * {@code testReleasingOnePositionLeavesTheOthers} is the case that separates them and is the only + * reason the word "the entry of this position" in the class under test is a claim rather than a hope. + *

+ * + * @author TheMeinerLP + * @version 1.1.0 + * @since 0.4.0 + */ +@ExtendWith(MicrotusExtension.class) +@DisplayName("The viewer cache entry of a chunk") +class ChunkViewerCacheTest { + + /** + * Creates a registered instance in the environment of the test. + * + * @param env the environment which provides the server process + * @return the registered instance + */ + private static FalcoInstance registered(Env env) { + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + return instance; + } + + @Test + @DisplayName("is created by the chunk constructor and removed by the release") + void testTheEntryCanBeReleased(Env env) { + final FalcoInstance instance = registered(env); + final int before = ChunkViewerCache.size(instance); + + new net.onelitefeather.falco.instance.FalcoChunk(instance, 4, 4); + assertEquals(before + 1, ChunkViewerCache.size(instance), + "constructing a chunk has to leave exactly one entry behind, or this test is measuring " + + "something other than the leak it is named after"); + + assertTrue(ChunkViewerCache.release(instance, 4, 4)); + assertEquals(before, ChunkViewerCache.size(instance)); + } + + /** + * Establishes that a release takes the entry of the position it was given and no other. + *

+ * The other three cases hold at most one entry at a time, so each of them is satisfied by a + * {@code release} which empties the whole map — the mutation which replaces the body with + * {@code viewers.clear()} keeps all three green. This case holds two entries and releases one, so + * it fails on that mutation twice over: the size after the release is the size of the map minus + * one entry, and the surviving position still has an entry to give back. + *

+ * + * @param env the environment which provides the server process + */ + @Test + @DisplayName("takes the entry of the position it was given and no other") + void testReleasingOnePositionLeavesTheOthers(Env env) { + final FalcoInstance instance = registered(env); + final int before = ChunkViewerCache.size(instance); + + new net.onelitefeather.falco.instance.FalcoChunk(instance, 4, 4); + new net.onelitefeather.falco.instance.FalcoChunk(instance, 9, 9); + assertEquals(before + 2, ChunkViewerCache.size(instance), + "two chunks at two positions have to leave two entries, or this case cannot tell a " + + "targeted removal from a wipe either"); + + assertTrue(ChunkViewerCache.release(instance, 4, 4)); + assertEquals(before + 1, ChunkViewerCache.size(instance), + "releasing one position has to cost exactly one entry, not the whole map"); + assertTrue(ChunkViewerCache.release(instance, 9, 9), + "the entry of the position that was not released has to still be there"); + assertEquals(before, ChunkViewerCache.size(instance)); + } + + @Test + @DisplayName("reports that there was nothing to release when there was not") + void testReleasingNothing(Env env) { + final FalcoInstance instance = registered(env); + + assertFalse(ChunkViewerCache.release(instance, 77, 77), + "no chunk was ever built at that position, so no entry can be removed"); + } + + @Test + @DisplayName("leaves the cache where it found it across a load and an unload") + void testALoadAndUnloadCycleIsNeutral(Env env) { + final FalcoInstance instance = registered(env); + final int before = ChunkViewerCache.size(instance); + + for (int round = 0; round < 32; round++) { + instance.unloadChunk(instance.loadChunk(round, 0).join()); + } + + assertEquals(before, ChunkViewerCache.size(instance), + "thirty-two load and unload cycles have to leave the cache exactly as they found it"); + } +} diff --git a/falco-instance/src/test/java/net/onelitefeather/falco/instance/BlockStorageTest.java b/falco-instance/src/test/java/net/onelitefeather/falco/instance/BlockStorageTest.java new file mode 100644 index 0000000..053298d --- /dev/null +++ b/falco-instance/src/test/java/net/onelitefeather/falco/instance/BlockStorageTest.java @@ -0,0 +1,435 @@ +package net.onelitefeather.falco.instance; + +import net.kyori.adventure.key.Key; +import net.minestom.server.MinecraftServer; +import net.minestom.server.coordinate.CoordConversion; +import net.minestom.server.instance.Section; +import net.minestom.server.instance.block.Block; +import net.minestom.server.registry.RegistryKey; +import net.minestom.server.world.biome.Biome; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.Arguments; +import org.junit.jupiter.params.provider.MethodSource; + +import java.util.ArrayList; +import java.util.List; +import java.util.function.Supplier; +import java.util.stream.Stream; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNotEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNotSame; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertThrows; + +/** + * Pins down the contract of {@link BlockStorage} on every implementation of it, which since stage 2 + * means {@link SectionBlockStorage} and {@link LazySectionBlockStorage} running the same cases from + * the same file. + *

+ * Everything here therefore goes through the interface and never through a section, with two + * deliberate exceptions. The tests that pin the height arithmetic and the unknown state read + * through {@link BlockStorage#section(int)}, because those are precisely the properties an + * assertion phrased in terms of {@code getBlock} alone cannot see. The view tests read through + * {@link BlockStorage#view(int)} and {@link BlockStorage#views()} for the same reason: whether a + * view is the live section or a copy of it is invisible to {@code getBlock}, which would answer + * from the storage either way. + *

+ * + *

Why the layout is a parameter rather than a second file

+ *

+ * A lazy layout is only worth having if it is indistinguishable from the eager one through this + * interface, so the cases that say what the interface promises must not be rewritten for it — a + * second file would drift, and the first thing to drift would be exactly the guard the second layout + * is most likely to lose. {@link #storages()} therefore names the layouts and every case takes a + * factory rather than calling one. What the lazy layout does beyond the contract lives in + * {@code LazySectionBlockStorageTest}, because none of it can be phrased about the eager one. + *

+ *

+ * Three cases stayed behind as plain tests over {@link SectionBlockStorage}, and the reason is the + * same for all three: they are statements about the eager layout rather than about the interface. + * A storage that shares nothing, a view that is the section itself and a section list that exists + * without being asked for are all false for the lazy layout by construction, and running them + * against it would either fail or — worse — force it to materialise everything and quietly assert + * the opposite of what stage 2 is about. + *

+ * + *

Why the height tests name the section

+ *

+ * A storage that spans sections {@code -4} to {@code 19} has to subtract its bottom section from + * every height it is given. Reading back what was written proves nothing about that subtraction: a + * storage that forgot it entirely is still self-consistent, since a write and a read of the same + * height land in the same wrong section, and every assertion of the form "what went in comes out" + * stays green. That is not a hypothetical — it was the state of this file when the storage was + * introduced, where every case sat at {@code y = 0..3} and the offset could have been deleted with + * all five tests still passing. Naming the section a height belongs to is what turns the offset into + * something a test can be wrong about, and the heights below are chosen so that both signs and both + * ends of the world are covered. + *

+ * + *

Why the biome cases exist at all

+ *

+ * A biome is stored as a registry id, and a registry answers a lookup miss with {@code -1} rather + * than with an exception. A palette validates its coordinates and never its values, so an + * unregistered biome is accepted, counted and serialised like any other — the failure surfaces on a + * read somewhere else, or on a client, and by then nothing points back to the write. The two guards + * against that are the kind that quietly stop existing during a refactor, because no ordinary + * round trip touches them. + *

+ * + * @author TheMeinerLP + * @version 3.0.0 + * @since 0.4.0 + */ +@DisplayName("The block storage of a chunk") +class BlockStorageTest { + + private static final int SECTIONS = 24; + private static final int MIN_SECTION = -4; + + @BeforeAll + static void server() { + if (MinecraftServer.process() == null) { + MinecraftServer.init(); + } + } + + /** + * The layouts every case of this file runs against. + * + * @return the name of each layout and a factory for an empty storage of it + */ + static Stream storages() { + return Stream.of( + Arguments.of("eager", + (Supplier) () -> new SectionBlockStorage(MIN_SECTION, SECTIONS)), + Arguments.of("lazy", + (Supplier) () -> new LazySectionBlockStorage(MIN_SECTION, SECTIONS))); + } + + /** + * The heights that pin the section arithmetic, once per layout. + *

+ * Built as a product rather than written out, so that adding a layout cannot leave a height + * untested for it, and adding a height cannot leave a layout untested for that height. + *

+ * + * @return the layout, its factory, a world height and the section that height belongs to + */ + static Stream heights() { + final int[][] cases = {{-64, 0}, {-49, 0}, {-48, 1}, {-1, 3}, {0, 4}, {127, 11}, {300, 22}, {319, 23}}; + + return product(cases); + } + + /** + * The columns outside the chunk that have to be refused, once per layout. + * + * @return the layout, its factory and a column that does not belong to the chunk + */ + static Stream columns() { + final int[][] cases = {{16, 0}, {-1, 0}, {0, 16}, {0, -1}, {48, 48}}; + + return product(cases); + } + + /** + * Combines every layout with every pair of a case table. + * + * @param cases the pairs, each of which becomes one case per layout + * @return the layout name, its factory and the two values of the pair + */ + private static Stream product(int[][] cases) { + final List combined = new ArrayList<>(); + + storages().forEach(layout -> { + for (int[] values : cases) { + combined.add(Arguments.of(layout.get()[0], layout.get()[1], values[0], values[1])); + } + }); + return combined.stream(); + } + + @ParameterizedTest(name = "{0}") + @MethodSource("storages") + @DisplayName("returns air for a position nothing was written to") + void testEmptyReadsAir(String name, Supplier factory) { + assertEquals(Block.AIR, factory.get().getBlock(0, 0, 0, Block.Getter.Condition.NONE)); + } + + @ParameterizedTest(name = "{0}") + @MethodSource("storages") + @DisplayName("returns what was written, at the position it was written to") + void testWriteThenRead(String name, Supplier factory) { + final BlockStorage storage = factory.get(); + + storage.setBlock(1, 2, 3, Block.STONE); + + assertEquals(Block.STONE, storage.getBlock(1, 2, 3, Block.Getter.Condition.NONE)); + assertEquals(Block.AIR, storage.getBlock(1, 2, 4, Block.Getter.Condition.NONE)); + } + + @ParameterizedTest(name = "{0}: y = {2} belongs to section {3}") + @MethodSource("heights") + @DisplayName("writes a height into the section that height belongs to, and into no other") + void testHeightSelectsItsSection(String name, Supplier factory, int y, int expectedSection) { + final BlockStorage storage = factory.get(); + + storage.setBlock(1, y, 3, Block.STONE); + + assertEquals(Block.STONE.stateId(), + storage.section(expectedSection).blockPalette() + .get(1, CoordConversion.globalToSectionRelative(y), 3), + "the block has to sit in section " + expectedSection); + assertEquals(Block.STONE, storage.getBlock(1, y, 3, Block.Getter.Condition.NONE)); + + int written = 0; + for (int section = 0; section < storage.sectionCount(); section++) { + written += storage.section(section).blockPalette().count(); + } + assertEquals(1, written, "exactly one section of the storage may hold a block"); + } + + @ParameterizedTest(name = "{0}") + @MethodSource("storages") + @DisplayName("spans one section per section of the chunk") + void testSectionCount(String name, Supplier factory) { + assertEquals(SECTIONS, factory.get().sectionCount()); + } + + /** + * The eager storage holds a section list before anyone asks for one. + *

+ * Not parameterised, and the omission is the point rather than an oversight: + * {@link BlockStorage#sections()} is the boundary method, so asking the lazy storage for its list + * materialises every section of it. A case that asserted the size of that list for both layouts + * would be asserting that the lazy one gives up its whole saving on being asked a question about + * its size. What the lazy layout does at that boundary is pinned in + * {@code LazySectionBlockStorageTest} instead, where the materialisation is the subject rather + * than a side effect. + *

+ */ + @Test + @DisplayName("holds one section per section of the chunk when it holds them eagerly") + void testEagerStorageHoldsEverySection() { + assertEquals(SECTIONS, new SectionBlockStorage(MIN_SECTION, SECTIONS).sections().size()); + } + + @ParameterizedTest(name = "{0}") + @MethodSource("storages") + @DisplayName("copies without sharing storage with the original") + void testCopyIsIndependent(String name, Supplier factory) { + final BlockStorage original = factory.get(); + original.setBlock(1, 2, 3, Block.STONE); + + final BlockStorage copy = original.copy(); + copy.setBlock(1, 2, 3, Block.DIRT); + + assertNotSame(original, copy); + assertEquals(Block.STONE, original.getBlock(1, 2, 3, Block.Getter.Condition.NONE)); + assertEquals(Block.DIRT, copy.getBlock(1, 2, 3, Block.Getter.Condition.NONE)); + } + + @ParameterizedTest(name = "{0}") + @MethodSource("storages") + @DisplayName("copies the height of every block along with it") + void testCopyKeepsTheHeights(String name, Supplier factory) { + final BlockStorage original = factory.get(); + original.setBlock(1, -64, 3, Block.STONE); + original.setBlock(1, 300, 3, Block.DIRT); + + final BlockStorage copy = original.copy(); + + assertEquals(Block.STONE, copy.getBlock(1, -64, 3, Block.Getter.Condition.NONE)); + assertEquals(Block.DIRT, copy.getBlock(1, 300, 3, Block.Getter.Condition.NONE)); + assertEquals(Block.STONE.stateId(), + copy.section(0).blockPalette().get(1, 0, 3)); + assertEquals(Block.DIRT.stateId(), + copy.section(22).blockPalette().get(1, 12, 3)); + } + + @ParameterizedTest(name = "{0}") + @MethodSource("storages") + @DisplayName("reads air everywhere after being cleared") + void testClear(String name, Supplier factory) { + final BlockStorage storage = factory.get(); + storage.setBlock(1, 2, 3, Block.STONE); + + storage.clear(); + + assertEquals(Block.AIR, storage.getBlock(1, 2, 3, Block.Getter.Condition.NONE)); + } + + /** + * A raw state id written past the storage must not come back as {@code null}. + *

+ * The value is written through the palette on purpose, because that is how it gets there in + * production: a generator fork and every chunk loader write state ids into + * {@code section.blockPalette()} directly, without passing a {@link Block} that could have been + * validated first. {@code Block.Getter.Condition#NONE} promises a block no matter what, and + * callers of {@code Block.Getter#getBlock(int, int, int)} dereference the result. + *

+ *

+ * What this test does not do is exercise the air fallback of the storage, and saying so + * is more useful than pretending otherwise. Minestom as pinned here has no state id below + * {@code Block#statesCount()} that is not a block — its table is a {@code List#of}, which cannot + * hold a null — so the fallback is unreachable and removing it would leave this file green. The + * two cases below are the two that do exist: the highest id the table holds, which has to answer + * with a block, and the first id past it, which has to fail out loud exactly as + * {@code DynamicChunk} fails rather than being quietly reported as air. + *

+ */ + @ParameterizedTest(name = "{0}") + @MethodSource("storages") + @DisplayName("answers every state id its table holds with a block and refuses one it does not") + void testRawStateIdsAreNeverAnsweredWithNull(String name, Supplier factory) { + final BlockStorage storage = factory.get(); + + storage.section(4).blockPalette().set(1, 2, 3, Block.statesCount() - 1); + assertNotNull(storage.getBlock(1, 2, 3, Block.Getter.Condition.NONE), + "the highest state id of the table has to be a block"); + + storage.section(4).blockPalette().set(1, 2, 3, Block.statesCount()); + assertThrows(IndexOutOfBoundsException.class, + () -> storage.getBlock(1, 2, 3, Block.Getter.Condition.NONE), + "a state id past the table has to fail rather than be reported as some block"); + } + + @ParameterizedTest(name = "{0}") + @MethodSource("storages") + @DisplayName("returns the biome that was written") + void testBiomeRoundTrip(String name, Supplier factory) { + final BlockStorage storage = factory.get(); + // Minestom keeps its Biomes constants package private, so the key is resolved through the + // registry. Desert rather than plains because an empty biome palette reads back as id zero, + // and a round trip through the id an empty palette already answers with proves nothing. + final RegistryKey desert = MinecraftServer.getBiomeRegistry().getKey(Key.key("minecraft:desert")); + + assertNotNull(desert, "the fixture needs a registered biome"); + assertNotEquals(0, MinecraftServer.getBiomeRegistry().getId(desert), + "the fixture needs a biome whose id is not the one an empty palette reads back"); + + storage.setBiome(4, 20, 8, desert); + + assertEquals(desert, storage.getBiome(4, 20, 8)); + } + + /** + * An unregistered biome has to be rejected at the write. + *

+ * {@code Registry#getId} answers a miss with {@code -1} and a palette takes that value like any + * other, so a storage without this guard stores a biome that does not exist, raises the entry + * count for it and hands it to the chunk packet. + *

+ */ + @ParameterizedTest(name = "{0}") + @MethodSource("storages") + @DisplayName("refuses to write a biome that is not registered") + void testUnregisteredBiomeIsRejected(String name, Supplier factory) { + final BlockStorage storage = factory.get(); + final RegistryKey unregistered = RegistryKey.unsafeOf("falco:not_a_biome"); + + assertThrows(IllegalStateException.class, () -> storage.setBiome(4, 20, 8, unregistered)); + assertEquals(0, storage.section(5).biomePalette().count(), + "a rejected biome must not have reached the palette"); + } + + @ParameterizedTest(name = "{0}") + @MethodSource("storages") + @DisplayName("refuses to read a biome id that is not registered") + void testUnregisteredBiomeIdIsRejectedOnRead(String name, Supplier factory) { + final BlockStorage storage = factory.get(); + final int unregisteredId = 30_000; + + assertNull(MinecraftServer.getBiomeRegistry().getKey(unregisteredId), + "the fixture needs a biome id that is not registered"); + + storage.section(5).biomePalette().set(1, 1, 2, unregisteredId); + + // NullPointerException rather than IllegalStateException because this is the exception + // DynamicChunk#getBiome raises through Check.notNull, and stage 1 is behavioural parity. + assertThrows(NullPointerException.class, () -> storage.getBiome(4, 20, 8)); + } + + /** + * A column outside the chunk has to fail rather than be folded back into it. + *

+ * {@link BlockStorage} states that {@code x} and {@code z} are already chunk-local, and this is + * the test that makes the statement worth something. An implementation that masks instead would + * accept a coordinate belonging to a chunk far away and write it into this one, which reads + * exactly like a correct write from every other angle. + *

+ *

+ * The exception type is deliberately not pinned any tighter than {@code RuntimeException}. It + * comes out of whatever the layout uses underneath — an {@code IllegalArgumentException} from + * the palette here, an {@code IndexOutOfBoundsException} from an array in a packed layout — and + * the contract is that the storage refuses, not which class it refuses with. + *

+ *

+ * The block written is stone rather than air on purpose. A lazy layout skips a write of the + * state its shared section already holds without ever reaching a palette, so a case phrased with + * air would be refused by the eager storage and silently accepted by the lazy one — and would be + * reporting the skip rather than the missing guard. + *

+ */ + @ParameterizedTest(name = "{0}: x = {2}, z = {3}") + @MethodSource("columns") + @DisplayName("refuses a column outside the chunk instead of folding it back in") + void testColumnOutsideTheChunkIsRejected(String name, Supplier factory, int x, int z) { + final BlockStorage storage = factory.get(); + + assertThrows(RuntimeException.class, () -> storage.setBlock(x, 20, z, Block.STONE)); + } + + @Test + @DisplayName("reports every section as materialised when it holds one of its own") + void testEagerStorageSharesNothing() { + final BlockStorage storage = new SectionBlockStorage(MIN_SECTION, SECTIONS); + + assertEquals(SECTIONS, storage.materialisedSections()); + for (int section = 0; section < SECTIONS; section++) { + assertFalse(storage.shared(section), + "section " + section + " of an eager storage cannot be shared"); + } + } + + @Test + @DisplayName("hands out the same section through the view as through the boundary") + void testViewAndSectionAgree() { + final BlockStorage storage = new SectionBlockStorage(MIN_SECTION, SECTIONS); + + storage.setBlock(1, 2, 3, Block.STONE); + + assertSame(storage.section(0), storage.view(0), + "an eager storage has nothing to materialise, so the two accessors are one"); + assertEquals(SECTIONS, storage.views().size()); + for (int section = 0; section < SECTIONS; section++) { + assertSame(storage.sections().get(section), storage.views().get(section), + "the view of section " + section + " has to be the section itself"); + } + } + + @ParameterizedTest(name = "{0}") + @MethodSource("storages") + @DisplayName("keeps the view in step with what was written after it was handed out") + void testViewFollowsLaterWrites(String name, Supplier factory) { + final BlockStorage storage = factory.get(); + final List
views = storage.views(); + + // y = 2 lands in section 4 of this fixture (MIN_SECTION = -4), the same section + // testHeightSelectsItsSection pins for y = 0. See the concern in task-1-report.md: the + // brief's version of this test read views.get(0), which is only the section a write to + // y = 2 would land in for a storage whose bottom section is 0, not -4. + storage.setBlock(1, 2, 3, Block.STONE); + + assertEquals(Block.STONE.stateId(), views.get(4).blockPalette().get(1, 2, 3), + "a view that was taken before a write has to show the write, or a caller which " + + "holds one is reading a chunk that no longer exists"); + } +} diff --git a/falco-instance/src/test/java/net/onelitefeather/falco/instance/BlockWriterTest.java b/falco-instance/src/test/java/net/onelitefeather/falco/instance/BlockWriterTest.java new file mode 100644 index 0000000..0d6d9db --- /dev/null +++ b/falco-instance/src/test/java/net/onelitefeather/falco/instance/BlockWriterTest.java @@ -0,0 +1,350 @@ +package net.onelitefeather.falco.instance; + +import net.kyori.adventure.key.Key; +import net.minestom.server.MinecraftServer; +import net.minestom.server.coordinate.BlockVec; +import net.minestom.server.event.instance.InstanceBlockUpdateEvent; +import net.minestom.server.instance.block.Block; +import net.minestom.server.instance.block.BlockHandler; +import net.minestom.server.instance.block.rule.BlockPlacementRule; +import net.minestom.server.world.DimensionType; +import net.minestom.testing.Env; +import net.minestom.testing.extension.MicrotusExtension; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; + +import java.util.UUID; +import java.util.concurrent.atomic.AtomicBoolean; +import java.util.concurrent.atomic.AtomicInteger; + +import static org.junit.jupiter.api.Assertions.assertDoesNotThrow; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNotEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Drives the block writer of a Falco instance directly. + *

+ * Two properties are asserted here that cannot be asserted through the instance: that a write into a + * chunk which is handed in never consults the registry at all, and that the write lock of that chunk + * is no longer held while the neighbour pass and the update event run. The second is what NFR-006 is + * about and it used to be unobservable, because the only entry point took the lock, wrote, released + * it and ran three more things, all inside one {@code private} method. + *

+ *

+ * The lock cases measure from inside the callbacks, not after the write returned. A check + * after {@code write} has returned proves nothing: the lock of a chunk is a + * {@code ReentrantReadWriteLock}, so a writer which released it one line too late has still released + * it by the time the caller looks, and the same thread could take it again either way. The two things + * NFR-006 actually promises — that a rule reshaping a neighbour and a listener of + * {@code InstanceBlockUpdateEvent} run with no chunk lock held — are only observable from within + * those two, which is what {@code holdsWriteLock()} is read for here. + *

+ *

+ * The same reading is taken from the other side. Three cases assert that the placement rule, the two + * block handlers and the lifecycle listener of the chunk do run under the write lock, because + * that is what the class documentation of {@link BlockWriter} now says and a documented lock rule + * nobody measures is how the previous wording came to claim the opposite of what the code did — and, + * for the listener, how that same wording came to enumerate three pieces of foreign code under the + * lock while the code ran four. + *

+ * + * @author TheMeinerLP + * @version 1.2.0 + * @since 0.4.0 + */ +@ExtendWith(MicrotusExtension.class) +@DisplayName("The block writer of a Falco instance") +class BlockWriterTest { + + /** + * The height every case writes at. + */ + private static final int Y = 64; + + /** + * A handler which counts how often a block carrying it reached a chunk. + *

+ * Counting the calls of {@code onPlace} rather than reading the block back is what makes the + * recursion guard observable at all: the guard drops a second write of the same block to the same + * position, and a dropped write leaves the chunk holding exactly what a performed write would have + * left it holding. + *

+ * + * @param writes the counter raised once per write which reached the chunk + */ + private record CountingHandler(AtomicInteger writes) implements BlockHandler { + + @Override + public void onPlace(Placement placement) { + this.writes.incrementAndGet(); + } + + @Override + public Key getKey() { + return Key.key("falco", "counting-writer"); + } + } + + /** + * A handler which records whether the write lock of a chunk was held while it was called. + *

+ * Read from within the callbacks for the same reason the two neighbour cases are: whether a lock + * was held during a call is not answerable once that call returned. + *

+ * + * @param chunk the chunk whose write lock is probed + * @param places the counter raised once per {@code onPlace} + * @param destroys the counter raised once per {@code onDestroy} + * @param placeUnderLock whether the write lock was held during the last {@code onPlace} + * @param destroyUnderLock whether the write lock was held during the last {@code onDestroy} + */ + private record LockProbeHandler(FalcoChunk chunk, AtomicInteger places, AtomicInteger destroys, + AtomicBoolean placeUnderLock, AtomicBoolean destroyUnderLock) + implements BlockHandler { + + @Override + public void onPlace(Placement placement) { + this.places.incrementAndGet(); + this.placeUnderLock.set(this.chunk.holdsWriteLock()); + } + + @Override + public void onDestroy(Destroy destroy) { + this.destroys.incrementAndGet(); + this.destroyUnderLock.set(this.chunk.holdsWriteLock()); + } + + @Override + public Key getKey() { + return Key.key("falco", "lock-probe-writer"); + } + } + + /** + * Creates a registered instance in the environment of the test. + * + * @param env the environment which provides the server process + * @return the registered instance + */ + private static FalcoInstance registered(Env env) { + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + return instance; + } + + @Test + @DisplayName("writes into the chunk it was handed, without asking where that chunk is") + void testWriteIntoAChunkThatIsNotInTheRegistry(Env env) { + final FalcoInstance instance = registered(env); + final BlockWriter writer = instance.blockWriter(); + final FalcoChunk orphan = new FalcoChunk(instance, 9, 9); + + writer.write(orphan, 144, Y, 144, Block.STONE, null, null, false, 0); + + orphan.lockReadLock(); + try { + assertEquals(Block.STONE, orphan.getBlock(144, Y, 144)); + } finally { + orphan.unlockReadLock(); + } + assertTrue(instance.getChunks().isEmpty(), "the writer must not have published anything"); + } + + @Test + @DisplayName("lets a neighbour reshape itself with no write lock of the written chunk held") + void testTheNeighbourPassRunsOutsideTheChunkLock(Env env) { + final FalcoInstance instance = registered(env); + final BlockWriter writer = instance.blockWriter(); + final FalcoChunk chunk = FalcoChunk.require(instance.loadChunk(0, 0).join()); + final AtomicInteger updates = new AtomicInteger(); + final AtomicBoolean lockHeld = new AtomicBoolean(); + MinecraftServer.getBlockManager().registerBlockPlacementRule(new BlockPlacementRule(Block.GLASS) { + + @Override + public Block blockUpdate(UpdateState state) { + updates.incrementAndGet(); + lockHeld.set(chunk.holdsWriteLock()); + return Block.GLOWSTONE; + } + + @Override + public Block blockPlace(PlacementState state) { + return state.block(); + } + }); + instance.setBlock(2, Y, 1, Block.GLASS); + + writer.write(chunk, 1, Y, 1, Block.STONE, null, null, true, 0); + + assertTrue(updates.get() > 0, "the neighbour of the written block has to be asked to reshape itself"); + assertFalse(lockHeld.get(), + "the neighbour pass may not run under the write lock of the chunk that was written; a " + + "neighbour in another chunk would take a second chunk lock while the first is held"); + } + + @Test + @DisplayName("dispatches the block update event with no write lock of the written chunk held") + void testTheUpdateEventRunsOutsideTheChunkLock(Env env) { + final FalcoInstance instance = registered(env); + final BlockWriter writer = instance.blockWriter(); + final FalcoChunk chunk = FalcoChunk.require(instance.loadChunk(0, 0).join()); + final AtomicInteger events = new AtomicInteger(); + final AtomicBoolean lockHeld = new AtomicBoolean(); + MinecraftServer.getGlobalEventHandler().addListener(InstanceBlockUpdateEvent.class, event -> { + events.incrementAndGet(); + lockHeld.set(chunk.holdsWriteLock()); + }); + + writer.write(chunk, 3, Y, 3, Block.STONE, null, null, false, 0); + + assertEquals(1, events.get(), "a write has to announce itself exactly once"); + assertFalse(lockHeld.get(), + "a listener of the update event is arbitrary foreign code and may not run under a chunk lock"); + } + + @Test + @DisplayName("asks the placement rule while the write lock of the chunk is held") + void testThePlacementRuleRunsUnderTheChunkLock(Env env) { + final FalcoInstance instance = registered(env); + final BlockWriter writer = instance.blockWriter(); + final FalcoChunk chunk = FalcoChunk.require(instance.loadChunk(0, 0).join()); + final AtomicInteger placements = new AtomicInteger(); + final AtomicBoolean lockHeld = new AtomicBoolean(); + MinecraftServer.getBlockManager().registerBlockPlacementRule(new BlockPlacementRule(Block.DIAMOND_BLOCK) { + + @Override + public Block blockPlace(PlacementState state) { + placements.incrementAndGet(); + lockHeld.set(chunk.holdsWriteLock()); + return state.block(); + } + }); + final BlockVec position = new BlockVec(5, Y, 5); + + writer.write(chunk, position.blockX(), position.blockY(), position.blockZ(), Block.DIAMOND_BLOCK, + new BlockHandler.Placement(Block.DIAMOND_BLOCK, Block.AIR, instance, position), null, true, 0); + + assertEquals(1, placements.get(), "a placement whose block carries a rule has to reach that rule"); + assertTrue(lockHeld.get(), + "the placement rule decides what the block is and therefore runs under the write lock; the " + + "class documentation says so and this is what says it is still true"); + } + + @Test + @DisplayName("runs the handlers of the old and the new block while the write lock of the chunk is held") + void testTheBlockHandlersRunUnderTheChunkLock(Env env) { + final FalcoInstance instance = registered(env); + final BlockWriter writer = instance.blockWriter(); + final FalcoChunk chunk = FalcoChunk.require(instance.loadChunk(0, 0).join()); + final LockProbeHandler probe = new LockProbeHandler(chunk, new AtomicInteger(), new AtomicInteger(), + new AtomicBoolean(), new AtomicBoolean()); + + writer.write(chunk, 7, Y, 7, Block.STONE.withHandler(probe), null, null, false, 0); + writer.write(chunk, 7, Y, 7, Block.DIRT.withHandler(probe), null, null, false, 0); + + assertEquals(2, probe.places().get(), "both written blocks carry a handler and both have to be placed"); + assertEquals(1, probe.destroys().get(), "the second write replaces the first block and has to destroy it"); + assertTrue(probe.placeUnderLock().get(), + "a block handler is foreign code that nonetheless runs under the chunk write lock, because it " + + "is told about the block while that block is being established"); + assertTrue(probe.destroyUnderLock().get(), + "the same holds for the handler of the block that was replaced"); + } + + @Test + @DisplayName("tells the lifecycle listener of the chunk while the write lock of that chunk is held") + void testTheLifecycleListenerRunsUnderTheChunkLock(Env env) { + final FalcoInstance instance = registered(env); + final BlockWriter writer = instance.blockWriter(); + final FalcoChunk chunk = FalcoChunk.require(instance.loadChunk(0, 0).join()); + final AtomicInteger changes = new AtomicInteger(); + final AtomicBoolean lockHeld = new AtomicBoolean(); + chunk.addLifecycleListener(new ChunkLifecycleListener() { + + @Override + public void onBlockChange(FalcoChunk written, int x, int y, int z, Block block) { + changes.incrementAndGet(); + lockHeld.set(written.holdsWriteLock()); + } + }); + + writer.write(chunk, 11, Y, 11, Block.STONE, null, null, false, 0); + + assertEquals(1, changes.get(), "a write into a chunk with a listener has to reach that listener once"); + assertTrue(lockHeld.get(), + "a lifecycle listener is the fourth piece of foreign code under the chunk write lock, and " + + "the only one a third party installs without touching a block; the class " + + "documentation of BlockWriter enumerates it and this is what says it is still true"); + } + + @Test + @DisplayName("refuses to write outside the world and says so instead of throwing") + void testAWriteOutsideTheWorldIsRefused(Env env) { + final FalcoInstance instance = registered(env); + final BlockWriter writer = instance.blockWriter(); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + final long before = writer.lastChangeTime(); + + assertDoesNotThrow(() -> writer.write(chunk, 0, 5000, 0, Block.STONE, null, null, false, 0), + "a height outside the world is refused rather than thrown about"); + + assertEquals(before, writer.lastChangeTime(), + "a refused write may not reach the timestamp, which is inside the lock and past the check"); + chunk.lockReadLock(); + try { + assertEquals(Block.AIR, chunk.getBlock(0, Y, 0), "nothing may have been written anywhere"); + } finally { + chunk.unlockReadLock(); + } + } + + @Test + @DisplayName("moves its own timestamp when a block reaches a chunk") + void testTheTimestampMoves(Env env) { + final FalcoInstance instance = registered(env); + final BlockWriter writer = instance.blockWriter(); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + final long before = writer.lastChangeTime(); + + writer.write(chunk, 0, Y, 0, Block.STONE, null, null, false, 0); + + assertNotEquals(before, writer.lastChangeTime(), + "a block write has to move the timestamp the batches read"); + } + + @Test + @DisplayName("drops a second write of the same block to the same position") + void testTheGuardDropsTheSecondWrite(Env env) { + final FalcoInstance instance = registered(env); + final BlockWriter writer = instance.blockWriter(); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + final AtomicInteger writes = new AtomicInteger(); + final Block counted = Block.STONE.withHandler(new CountingHandler(writes)); + + writer.write(chunk, 0, Y, 0, counted, null, null, false, 0); + writer.write(chunk, 0, Y, 0, counted, null, null, false, 0); + + assertEquals(1, writes.get(), + "the same block at the same position reaches the chunk once between two end of ticks"); + } + + @Test + @DisplayName("lets the same block be written again once its own tick ended") + void testEndTickClearsTheGuard(Env env) { + final FalcoInstance instance = registered(env); + final BlockWriter writer = instance.blockWriter(); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + final AtomicInteger writes = new AtomicInteger(); + final Block counted = Block.STONE.withHandler(new CountingHandler(writes)); + + writer.write(chunk, 0, Y, 0, counted, null, null, false, 0); + writer.endTick(); + writer.write(chunk, 0, Y, 0, counted, null, null, false, 0); + + assertEquals(2, writes.get(), + "the guard is scoped to one tick, so the same block can be written again afterwards"); + } +} diff --git a/falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkGenerationTest.java b/falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkGenerationTest.java new file mode 100644 index 0000000..92558d5 --- /dev/null +++ b/falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkGenerationTest.java @@ -0,0 +1,118 @@ +package net.onelitefeather.falco.instance; + +import net.minestom.server.MinecraftServer; +import net.minestom.server.coordinate.Vec; +import net.minestom.server.instance.block.Block; +import net.minestom.server.instance.generator.Generator; +import net.minestom.server.world.DimensionType; +import net.minestom.testing.Env; +import net.minestom.testing.extension.MicrotusExtension; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; + +import java.util.UUID; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertSame; + +/** + * Drives the generator side of a Falco instance without the instance. + *

+ * The fork bookkeeping used to be a {@code private} map of {@code FalcoInstance} and could only be + * observed through the world it eventually produced, which made a test of it a test of the whole load + * path. Here the map has a size that can be read, so the case that mattered — a fork for a chunk + * nobody ever asks for — is assertable instead of inferable. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ExtendWith(MicrotusExtension.class) +@DisplayName("The generator side of a Falco instance") +class ChunkGenerationTest { + + /** + * Creates a registered instance to build chunks for. + * + * @param env the environment which provides the server process + * @return the registered instance + */ + private static FalcoInstance registered(Env env) { + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + return instance; + } + + @Test + @DisplayName("has no generator until it is given one") + void testTheGeneratorIsHandedBack(Env env) { + registered(env); + final ChunkGeneration generation = new ChunkGeneration(MinecraftServer.process(), point -> null); + final Generator generator = unit -> unit.modifier().fillHeight(0, 16, Block.STONE); + + assertNull(generation.generator()); + generation.generator(generator); + assertSame(generator, generation.generator()); + } + + @Test + @DisplayName("writes what the generator produced into the chunk it was asked about") + void testAGeneratedChunkCarriesItsBlocks(Env env) { + final FalcoInstance instance = registered(env); + final ChunkGeneration generation = new ChunkGeneration(MinecraftServer.process(), point -> null); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + + generation.apply(chunk, unit -> unit.modifier().fillHeight(0, 16, Block.STONE)); + + chunk.lockReadLock(); + try { + assertEquals(Block.STONE, chunk.getBlock(0, 0, 0)); + assertEquals(Block.AIR, chunk.getBlock(0, 32, 0)); + } finally { + chunk.unlockReadLock(); + } + } + + @Test + @DisplayName("keeps a fork for a chunk which does not exist and delivers it when it does") + void testAPendingForkIsKeptAndDelivered(Env env) { + final FalcoInstance instance = registered(env); + final ChunkGeneration generation = new ChunkGeneration(MinecraftServer.process(), point -> null); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + + generation.apply(chunk, unit -> unit.fork(setter -> + setter.setBlock(new Vec(20, 0, 0), Block.STONE))); + + assertEquals(1, generation.pendingForks(), + "the fork landed in the chunk at 1:0, which does not exist, so it has to be remembered"); + + final FalcoChunk neighbour = new FalcoChunk(instance, 1, 0); + generation.applyPending(neighbour); + + assertEquals(0, generation.pendingForks(), "delivering a fork has to take it off the list"); + neighbour.lockReadLock(); + try { + assertEquals(Block.STONE, neighbour.getBlock(20, 0, 0)); + } finally { + neighbour.unlockReadLock(); + } + } + + @Test + @DisplayName("drops every pending fork when it is told to") + void testPendingForksCanBeDropped(Env env) { + final FalcoInstance instance = registered(env); + final ChunkGeneration generation = new ChunkGeneration(MinecraftServer.process(), point -> null); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + generation.apply(chunk, unit -> unit.fork(setter -> + setter.setBlock(new Vec(20, 0, 0), Block.STONE))); + + generation.clearPending(); + + assertEquals(0, generation.pendingForks(), + "a fork whose target chunk is never requested waits forever, so a shutdown has to drop it"); + } +} diff --git a/falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkLifecycleAllocationTest.java b/falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkLifecycleAllocationTest.java new file mode 100644 index 0000000..cc879e9 --- /dev/null +++ b/falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkLifecycleAllocationTest.java @@ -0,0 +1,115 @@ +package net.onelitefeather.falco.instance; + +import com.sun.management.ThreadMXBean; +import net.minestom.server.world.DimensionType; +import net.minestom.testing.Env; +import net.minestom.testing.extension.MicrotusExtension; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; + +import java.lang.management.ManagementFactory; +import java.util.UUID; + +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.junit.jupiter.api.Assumptions.assumeTrue; + +/** + * Counts what a lifecycle transition allocates, with no listener and with one, which is US-3.04. + *

+ * The requirement is that a chunk nobody listens to pays nothing per transition. That is a claim + * about an allocation, and an allocation is measured rather than argued: the two arms below run the + * identical loop and differ only in whether a listener is installed, and the difference between them + * is the cost of the event. + *

+ * + *

Why the listener arm has to publish the event

+ *

+ * A test which only measured the null arm would pass against an implementation that allocates an + * event on every transition, as long as escape analysis noticed that nothing escaped and deleted the + * allocation. The listener below therefore writes the event into a {@code static volatile} field, + * which no compiler may remove, so the second arm is a positive control: if it does not allocate, the + * measurement itself is broken and the first arm proves nothing. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ExtendWith(MicrotusExtension.class) +@DisplayName("What a lifecycle transition allocates") +class ChunkLifecycleAllocationTest { + + /** + * How many transitions each arm performs. + */ + private static final int TRANSITIONS = 200_000; + + /** + * How many transitions are run before the measurement, so both arms are compiled. + */ + private static final int WARMUP = 50_000; + + /** + * Where the listener arm publishes its events, so that nothing can be optimised away. + */ + private static volatile Object sink; + + /** + * Ticks a chunk the given number of times and reports what the calling thread allocated. + * + * @param chunk the chunk to tick + * @param times how often to tick it + * @return the bytes the calling thread allocated during the loop + */ + private static long allocatedWhileTicking(FalcoChunk chunk, int times) { + final ThreadMXBean threads = (ThreadMXBean) ManagementFactory.getThreadMXBean(); + final long before = threads.getCurrentThreadAllocatedBytes(); + + for (int index = 0; index < times; index++) { + chunk.tick(index); + } + return threads.getCurrentThreadAllocatedBytes() - before; + } + + @Test + @DisplayName("costs nothing without a listener and one event with one") + void testTheEventIsBuiltOnlyWhenSomebodyListens(Env env) { + final ThreadMXBean threads = (ThreadMXBean) ManagementFactory.getThreadMXBean(); + assumeTrue(threads.isThreadAllocatedMemorySupported(), + "this JVM cannot report per thread allocation, so the question cannot be answered here"); + threads.setThreadAllocatedMemoryEnabled(true); + + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + final FalcoChunk silent = new FalcoChunk(instance, 0, 0); + final FalcoChunk heard = new FalcoChunk(instance, 1, 0); + heard.addLifecycleListener(new ChunkLifecycleListener() { + + @Override + public void onTick(ChunkLifecycleEvent event) { + sink = event; + } + }); + + allocatedWhileTicking(silent, WARMUP); + allocatedWhileTicking(heard, WARMUP); + final long withoutListener = allocatedWhileTicking(silent, TRANSITIONS); + final long withListener = allocatedWhileTicking(heard, TRANSITIONS); + + System.out.printf("lifecycle transitions: %,d without a listener -> %,d B (%.3f B each)%n", + TRANSITIONS, withoutListener, (double) withoutListener / TRANSITIONS); + System.out.printf("lifecycle transitions: %,d with one listener -> %,d B (%.3f B each)%n", + TRANSITIONS, withListener, (double) withListener / TRANSITIONS); + + assertTrue(withListener >= 16L * TRANSITIONS, + "the positive control failed: a listener that stores its event has to allocate one per " + + "transition, but the arm with a listener allocated " + withListener + + " B over " + TRANSITIONS + " transitions, so this measurement cannot see " + + "allocations at all and its other half proves nothing"); + assertTrue(withoutListener < TRANSITIONS, + "a chunk nobody listens to allocated " + withoutListener + " B over " + TRANSITIONS + + " transitions, which is more than a byte each: the event is being built before " + + "the listener is checked"); + } +} diff --git a/falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkLifecycleListenerTest.java b/falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkLifecycleListenerTest.java new file mode 100644 index 0000000..3cf8d75 --- /dev/null +++ b/falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkLifecycleListenerTest.java @@ -0,0 +1,204 @@ +package net.onelitefeather.falco.instance; + +import net.minestom.server.MinecraftServer; +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.InstanceContainer; +import net.minestom.server.instance.block.Block; +import net.minestom.server.world.DimensionType; +import net.minestom.testing.Env; +import net.minestom.testing.extension.MicrotusExtension; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; + +import java.util.ArrayList; +import java.util.List; +import java.util.UUID; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertSame; + +/** + * Establishes that a chunk can carry more than one lifecycle extension, which is US-3.03. + *

+ * Before this stage a chunk had exactly one extension point and it was its superclass, so + * {@code FalcoLightingChunk} occupied it and nothing else could be installed beside light. Two + * listeners on one chunk, both notified on every transition, is the shape that removes that limit. + *

+ * + * @author TheMeinerLP + * @version 1.1.0 + * @since 0.4.0 + */ +@ExtendWith(MicrotusExtension.class) +@DisplayName("The lifecycle listeners of a chunk") +class ChunkLifecycleListenerTest { + + /** + * A listener which writes down what it was told, in order. + */ + private static final class Recording implements ChunkLifecycleListener { + + /** + * The name this listener writes in front of every entry. + */ + private final String name; + + /** + * Where the entries go. + */ + private final List log; + + /** + * Creates a recording listener. + * + * @param name the name of this listener + * @param log where the entries go + */ + private Recording(String name, List log) { + this.name = name; + this.log = log; + } + + @Override + public void onPublish(ChunkLifecycleEvent event) { + this.log.add(this.name + ":publish:" + event.chunk().getChunkX()); + } + + @Override + public void onLoad(ChunkLifecycleEvent event) { + this.log.add(this.name + ":load"); + } + + @Override + public void onTick(ChunkLifecycleEvent event) { + this.log.add(this.name + ":tick:" + event.time()); + } + + @Override + public void onUnload(ChunkLifecycleEvent event) { + this.log.add(this.name + ":unload"); + } + + @Override + public void onBlockChange(FalcoChunk chunk, int x, int y, int z, Block block) { + this.log.add(this.name + ":block:" + x + "/" + y + "/" + z); + } + } + + /** + * Creates a registered instance in the environment of the test. + * + * @param env the environment which provides the server process + * @return the registered instance + */ + private static FalcoInstance registered(Env env) { + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + return instance; + } + + @Test + @DisplayName("notifies both listeners on every transition, in registration order") + void testTwoListenersBothHearEverything(Env env) { + final FalcoInstance instance = registered(env); + final List log = new ArrayList<>(); + instance.lifecycle().addListener(new Recording("first", log)); + instance.lifecycle().addListener(new Recording("second", log)); + + final Chunk chunk = instance.loadChunk(0, 0).join(); + chunk.lockWriteLock(); + try { + FalcoChunk.require(chunk).setBlock(1, 64, 1, Block.STONE, null, null); + } finally { + chunk.unlockWriteLock(); + } + chunk.tick(7L); + instance.unloadChunk(chunk); + + assertEquals(List.of( + "first:publish:0", "second:publish:0", + "first:load", "second:load", + "first:block:1/64/1", "second:block:1/64/1", + "first:tick:7", "second:tick:7", + "first:unload", "second:unload"), log); + } + + @Test + @DisplayName("holds no listener until one is registered") + void testAChunkStartsWithoutAListener(Env env) { + final FalcoInstance instance = registered(env); + + assertNull(new FalcoChunk(instance, 0, 0).lifecycleListener(), + "a chunk nobody listens to has to hold null, not an empty composite"); + assertNull(instance.lifecycle().listener()); + } + + @Test + @DisplayName("keeps the single listener single when there is only one") + void testOneListenerIsNotWrapped(Env env) { + final FalcoInstance instance = registered(env); + final ChunkLifecycleListener only = new Recording("only", new ArrayList<>()); + + instance.lifecycle().addListener(only); + + assertSame(only, instance.lifecycle().listener(), + "one listener composes with nothing, so it has to be stored as it is"); + } + + @Test + @DisplayName("gives a chunk of a plain container a listener too") + void testAChunkCanCarryItsOwnListener(Env env) { + final FalcoInstance instance = registered(env); + final List log = new ArrayList<>(); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + + chunk.addLifecycleListener(new Recording("own", log)); + chunk.tick(3L); + + assertEquals(List.of("own:tick:3"), log, + "the listener lives on the chunk, so a chunk outside a Falco instance can carry one"); + } + + /** + * The load and the unload are reported to a chunk of a plain {@code InstanceContainer} as well. + *

+ * The two transitions are the ones a chunk is told about rather than ones it notices, and there + * are two doors into them. {@link FalcoInstance} drives {@link FalcoChunk#markLoaded()} and + * {@link FalcoChunk#markUnloaded()}; an {@code InstanceContainer} lives in the Minestom package + * and calls the {@code protected} {@code onLoad()} and {@code unload()} straight, from + * {@code retrieveChunk} and from {@code unloadChunk}. A report installed on the public pair would + * be silent for every chunk of a container, which is the same shape of defect the loader arm + * already produced once: two arms, one report. + *

+ *

+ * This case therefore drives the arm the rest of this class never touches. The publish is absent + * from the log on purpose — a container has no publish step, and nothing on a chunk marks one. + *

+ */ + @Test + @DisplayName("reports load and unload to a chunk a plain container drives") + void testAContainerReachesBothReportsThroughTheProtectedHooks() { + if (MinecraftServer.process() == null) MinecraftServer.init(); + final InstanceContainer container = MinecraftServer.getInstanceManager().createInstanceContainer(); + final List log = new ArrayList<>(); + container.setChunkSupplier((instance, chunkX, chunkZ) -> { + final FalcoChunk chunk = new FalcoChunk(instance, chunkX, chunkZ); + chunk.addLifecycleListener(new Recording("own", log)); + return chunk; + }); + + final Chunk chunk = container.loadChunk(0, 0).join(); + + assertEquals(List.of("own:load"), log, + "InstanceContainer#retrieveChunk calls the protected onLoad, so the report has to sit there"); + + container.unloadChunk(chunk); + + assertEquals(List.of("own:load", "own:unload"), log, + "and InstanceContainer#unloadChunk calls the protected unload, not markUnloaded"); + + MinecraftServer.getInstanceManager().unregisterInstance(container); + } +} diff --git a/falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkLifecycleTest.java b/falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkLifecycleTest.java new file mode 100644 index 0000000..19ce676 --- /dev/null +++ b/falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkLifecycleTest.java @@ -0,0 +1,405 @@ +package net.onelitefeather.falco.instance; + +import net.minestom.server.coordinate.CoordConversion; +import net.minestom.server.event.instance.InstanceChunkLoadEvent; +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.ChunkLoader; +import net.minestom.server.instance.DynamicChunk; +import net.minestom.server.instance.Instance; +import net.minestom.server.world.DimensionType; +import net.minestom.testing.Env; +import net.minestom.testing.extension.MicrotusExtension; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; +import org.jetbrains.annotations.Nullable; + +import java.util.ArrayList; +import java.util.List; +import java.util.UUID; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.CompletionException; +import java.util.concurrent.atomic.AtomicInteger; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertInstanceOf; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Reaches the publish and the load completion of a chunk without driving a full load, which is + * US-3.02. + *

+ * Both were {@code private} methods of {@code FalcoInstance} before this stage. The only way to run + * either of them was to ask the instance for a chunk, which meant that the case they exist for — + * a publish that is refused because an unload claimed the position while the loader was still + * working — could not be arranged from a test at all: it needs the two to interleave, and a caller + * driving the whole load path has no seam to interleave at. {@code FalcoInstanceLoadRaceTest} gets + * close by running a thousand loads and unloads against each other and hoping the window is hit; + * these cases hit it every time, deterministically, in a single thread. + *

+ *

+ * Three cases hand the load path a listener which throws, one per arm. They exist because stage 3 put + * arbitrary third-party code between the chunk being ready and its future being completed, and a + * throw out of that stretch used to leave the future uncompleted — which is a hang rather than a + * failure, and a hang no assertion of this class would have noticed. Each of them therefore asserts + * both halves: that the caller is told, and that the throw still leaves the load path. + *

+ * + * @author TheMeinerLP + * @version 1.1.0 + * @since 0.4.0 + */ +@ExtendWith(MicrotusExtension.class) +@DisplayName("The lifecycle of one chunk, driven step by step") +class ChunkLifecycleTest { + + /** + * The position every case works on. + */ + private static final long INDEX = CoordConversion.chunkIndex(0, 0); + + /** + * Creates a registered instance in the environment of the test. + * + * @param env the environment which provides the server process + * @return the registered instance + */ + private static FalcoInstance registered(Env env) { + return registered(env, null); + } + + /** + * Creates a registered instance with a loader in the environment of the test. + * + * @param env the environment which provides the server process + * @param loader the loader the instance reads from and reports removals to, null for none + * @return the registered instance + */ + private static FalcoInstance registered(Env env, @Nullable ChunkLoader loader) { + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD, loader); + env.process().instance().registerInstance(instance); + return instance; + } + + @Test + @DisplayName("publishes a chunk that was never loaded through a loader") + void testPublishWithoutALoad(Env env) { + final FalcoInstance instance = registered(env); + final ChunkLifecycle lifecycle = instance.lifecycle(); + final ChunkRegistry registry = instance.registry(); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + final CompletableFuture own = new CompletableFuture<>(); + registry.acquire(INDEX, own); + + assertTrue(lifecycle.publish(INDEX, chunk, own)); + + assertSame(chunk, instance.getChunk(0, 0)); + assertFalse(own.isDone(), + "publishing does not hand the chunk to the waiting callers; completeLoad does, and that is the split"); + assertEquals(0, registry.loading(), "the position is no longer busy once its chunk is there"); + } + + @Test + @DisplayName("refuses to publish a chunk whose position was claimed while it was being built") + void testPublishIsRefusedAfterADiscard(Env env) { + final FalcoInstance instance = registered(env); + final ChunkLifecycle lifecycle = instance.lifecycle(); + final ChunkRegistry registry = instance.registry(); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + final CompletableFuture own = new CompletableFuture<>(); + registry.acquire(INDEX, own); + + lifecycle.discard(INDEX); + + assertFalse(lifecycle.publish(INDEX, chunk, own), + "the position was claimed, so this chunk is not wanted any more"); + assertNull(instance.getChunk(0, 0)); + assertTrue(own.isCompletedExceptionally(), + "the discard is what tells the callers waiting for that load; a chunk handed back" + + " after it was claimed looks usable and is not"); + } + + @Test + @DisplayName("completes a load, runs the load hook of the chunk and fires the event exactly once") + void testCompleteLoadDrivenDirectly(Env env) { + final FalcoInstance instance = registered(env); + final ChunkLifecycle lifecycle = instance.lifecycle(); + lifecycle.supplier(Announcing::new); + final AtomicInteger events = new AtomicInteger(); + instance.eventNode().addListener(InstanceChunkLoadEvent.class, event -> events.incrementAndGet()); + final CompletableFuture own = new CompletableFuture<>(); + instance.registry().acquire(INDEX, own); + + lifecycle.completeLoad(INDEX, 0, 0, ChunkLoader.noop(), own); + + final Chunk chunk = own.join(); + // Not isLoaded(): a chunk reports that from the moment it is constructed, so asserting it + // here would pass against a completeLoad which never told the chunk anything at all. + assertTrue(assertInstanceOf(Announcing.class, chunk).announced, + "completeLoad is what runs the load hook of the chunk"); + assertSame(chunk, instance.getChunk(0, 0)); + assertEquals(1, events.get()); + } + + @Test + @DisplayName("hands a discarded load its failure, unmarks the chunk and tells the current loader") + void testCompleteLoadOnAClaimedPosition(Env env) { + final Removals removals = new Removals(); + final FalcoInstance instance = registered(env, removals); + final ChunkLifecycle lifecycle = instance.lifecycle(); + final CompletableFuture own = new CompletableFuture<>(); + instance.registry().acquire(INDEX, own); + lifecycle.discard(INDEX); + final List produced = new ArrayList<>(); + + // Deliberately not the loader of the instance: the chunk is read through the loader handed in + // here, while the removal is reported to whichever loader is current when the publish is + // refused. The two can differ and this case is where that is written down. + lifecycle.completeLoad(INDEX, 0, 0, new ChunkLoader() { + + @Override + public Chunk loadChunk(Instance owner, int chunkX, int chunkZ) { + final FalcoChunk chunk = new FalcoChunk(owner, chunkX, chunkZ); + produced.add(chunk); + return chunk; + } + + @Override + public void saveChunk(Chunk chunk) { + } + }, own); + + final CompletionException thrown = assertThrows(CompletionException.class, own::join); + assertSame(FalcoInstanceException.class, thrown.getCause().getClass(), + "a chunk handed back after it was discarded looks usable and is not"); + assertNull(instance.getChunk(0, 0)); + assertFalse(produced.getFirst().isLoaded(), + "a chunk which was refused has to stop reporting itself as loaded, or nothing will ever unload it"); + assertEquals(produced, removals.chunks, + "the loader which is current when the publish is refused is the one that is told"); + } + + @Test + @DisplayName("hands a failing loader back to the caller and gives up the slot") + void testAFailingLoaderReleasesThePosition(Env env) { + final FalcoInstance instance = registered(env); + final ChunkLifecycle lifecycle = instance.lifecycle(); + final CompletableFuture own = new CompletableFuture<>(); + instance.registry().acquire(INDEX, own); + + lifecycle.completeLoad(INDEX, 0, 0, new ChunkLoader() { + + @Override + public Chunk loadChunk(Instance owner, int chunkX, int chunkZ) { + throw new IllegalStateException("the region file is a directory"); + } + + @Override + public void saveChunk(Chunk chunk) { + } + }, own); + + assertThrows(CompletionException.class, own::join); + assertEquals(0, instance.registry().loading(), + "a failed load must not leave its position marked as busy forever"); + } + + @Test + @DisplayName("fails the load rather than hanging it when the publish listener throws") + void testAThrowingPublishListenerFailsTheLoad(Env env) { + final FalcoInstance instance = registered(env); + final ChunkLifecycle lifecycle = instance.lifecycle(); + final IllegalStateException refusal = new IllegalStateException("this scheduler already serves another instance"); + lifecycle.addListener(new ChunkLifecycleListener() { + + @Override + public void onPublish(ChunkLifecycleEvent event) { + throw refusal; + } + }); + final CompletableFuture own = new CompletableFuture<>(); + instance.registry().acquire(INDEX, own); + + assertSame(refusal, assertThrows(IllegalStateException.class, + () -> lifecycle.completeLoad(INDEX, 0, 0, ChunkLoader.noop(), own)), + "the throw is a defect of the listener and keeps going, exactly as it did before"); + + // Asked before it is joined, and this order is the point of the case: completeLoad ran on + // this thread, so a future which is not done here is never going to be, and a join would be + // the very wait for the life of the process this case is about rather than a failure. + assertTrue(own.isCompletedExceptionally(), + "every caller waiting on this position has to be told; an uncompleted future is not an" + + " error anybody can see, it is a wait for the life of the process"); + assertSame(refusal, assertThrows(CompletionException.class, own::join).getCause()); + assertNotNull(instance.getChunk(0, 0), + "the chunk entered the registry before the listener ran and the catch does not undo that"); + } + + @Test + @DisplayName("fails the load rather than hanging it when the load listener throws") + void testAThrowingLoadListenerFailsTheLoad(Env env) { + final FalcoInstance instance = registered(env); + final ChunkLifecycle lifecycle = instance.lifecycle(); + final IllegalStateException refusal = new IllegalStateException("this scheduler already serves another instance"); + lifecycle.addListener(new ChunkLifecycleListener() { + + @Override + public void onLoad(ChunkLifecycleEvent event) { + throw refusal; + } + }); + final AtomicInteger events = new AtomicInteger(); + instance.eventNode().addListener(InstanceChunkLoadEvent.class, event -> events.incrementAndGet()); + final CompletableFuture own = new CompletableFuture<>(); + instance.registry().acquire(INDEX, own); + + assertSame(refusal, assertThrows(IllegalStateException.class, + () -> lifecycle.completeLoad(INDEX, 0, 0, ChunkLoader.noop(), own))); + + assertTrue(own.isCompletedExceptionally(), + "the second arm of the load has the same hole as the first and is closed the same way"); + assertSame(refusal, assertThrows(CompletionException.class, own::join).getCause()); + assertEquals(0, events.get(), + "the load never finished, so nothing may have been told that it did"); + } + + @Test + @DisplayName("tells the loader about a discarded chunk even when the unload listener throws") + void testAThrowingUnloadListenerStillReleasesTheDiscardedChunk(Env env) { + final Removals removals = new Removals(); + final FalcoInstance instance = registered(env, removals); + final ChunkLifecycle lifecycle = instance.lifecycle(); + lifecycle.addListener(new ChunkLifecycleListener() { + + @Override + public void onUnload(ChunkLifecycleEvent event) { + throw new IllegalStateException("the listener of this chunk refuses to be torn down"); + } + }); + final CompletableFuture own = new CompletableFuture<>(); + // The position belongs to somebody else's load, which is what a discard followed by a new + // request leaves behind. A plain discard would complete `own` itself and hide the question + // this case asks: on this arm the refusal below is the only completion there is. + instance.registry().acquire(INDEX, new CompletableFuture<>()); + + assertThrows(IllegalStateException.class, + () -> lifecycle.completeLoad(INDEX, 0, 0, ChunkLoader.noop(), own)); + + assertTrue(own.isCompletedExceptionally(), + "nobody else is going to complete this future, so the refused arm has to"); + final CompletionException thrown = assertThrows(CompletionException.class, own::join); + assertSame(FalcoInstanceException.class, thrown.getCause().getClass(), + "the callers are told that their load was discarded before the chunk is told anything"); + assertEquals(1, removals.chunks.size(), + "the loader may hold bookkeeping for a chunk it never handed out, and a listener which" + + " throws on the way out must not turn that into a leak"); + } + + @Test + @DisplayName("creates a chunk through the supplier and refuses null") + void testCreateUsesTheSupplier(Env env) { + final FalcoInstance instance = registered(env); + final ChunkLifecycle lifecycle = instance.lifecycle(); + + assertSame(FalcoChunk.class, lifecycle.create(3, 4).getClass()); + + lifecycle.supplier((owner, chunkX, chunkZ) -> null); + assertThrows(FalcoInstanceException.class, () -> lifecycle.create(3, 4)); + } + + @Test + @DisplayName("lets a foreign chunk type through creation and refuses it at the load") + void testAForeignChunkTypeIsRefusedAtTheLoadRatherThanAtTheCreation(Env env) { + final FalcoInstance instance = registered(env); + final ChunkLifecycle lifecycle = instance.lifecycle(); + lifecycle.supplier(DynamicChunk::new); + + // Creation holds no opinion about the chunk type, because a caller which installed a + // lifecycle through FalcoInstance#setChunkLifecycle may legitimately supply a foreign one. + assertInstanceOf(DynamicChunk.class, lifecycle.create(3, 4)); + + final CompletableFuture own = new CompletableFuture<>(); + instance.registry().acquire(INDEX, own); + lifecycle.completeLoad(INDEX, 0, 0, ChunkLoader.noop(), own); + + final CompletionException thrown = assertThrows(CompletionException.class, own::join); + assertSame(FalcoInstanceException.class, thrown.getCause().getClass()); + assertNull(instance.getChunk(0, 0), "a chunk this instance cannot unload must never be published"); + } + + @Test + @DisplayName("unloads a chunk once and does nothing the second time") + void testUnloadIsIdempotent(Env env) { + final FalcoInstance instance = registered(env); + final ChunkLifecycle lifecycle = instance.lifecycle(); + final Chunk chunk = instance.loadChunk(0, 0).join(); + + lifecycle.unload(chunk); + lifecycle.unload(chunk); + + assertFalse(chunk.isLoaded()); + assertNull(instance.getChunk(0, 0)); + } + + /** + * A chunk which writes down that its load hook was run. + *

+ * {@code Chunk#onLoad()} sets no flag of its own — {@code isLoaded()} is true from construction — + * so it is the only thing that can tell a completed load apart from one which put the chunk into + * the registry and stopped there. + *

+ */ + private static final class Announcing extends FalcoChunk { + + /** + * Whether the load hook of this chunk was run. + */ + private boolean announced; + + /** + * Creates a chunk which has not been told anything yet. + * + * @param instance the instance the chunk belongs to + * @param chunkX the chunk X + * @param chunkZ the chunk Z + */ + private Announcing(Instance instance, int chunkX, int chunkZ) { + super(instance, chunkX, chunkZ); + } + + @Override + protected void onLoad() { + this.announced = true; + } + } + + /** + * A loader which writes down every chunk it was told about, in order. + */ + private static final class Removals implements ChunkLoader { + + /** + * The chunks this loader was told had left the instance. + */ + private final List chunks = new ArrayList<>(); + + @Override + public @Nullable Chunk loadChunk(Instance instance, int chunkX, int chunkZ) { + return null; + } + + @Override + public void saveChunk(Chunk chunk) { + } + + @Override + public void unloadChunk(Chunk chunk) { + this.chunks.add(chunk); + } + } +} diff --git a/falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkLookupAllocationTest.java b/falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkLookupAllocationTest.java new file mode 100644 index 0000000..dd7e13d --- /dev/null +++ b/falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkLookupAllocationTest.java @@ -0,0 +1,111 @@ +package net.onelitefeather.falco.instance; + +import com.sun.management.ThreadMXBean; +import net.minestom.server.world.DimensionType; +import net.minestom.testing.Env; +import net.minestom.testing.extension.MicrotusExtension; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; + +import java.lang.management.ManagementFactory; +import java.util.UUID; + +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertTrue; +import static org.junit.jupiter.api.Assumptions.assumeTrue; + +/** + * Counts what looking a chunk up allocates, which is US-3.05. + *

+ * A {@code ConcurrentHashMap} boxes its key on every call, and the chunk index of a + * position is normally far outside the range {@code Long#valueOf} caches, so every lookup is an + * object that lives until the next young collection. This counts them. It says nothing about time, + * on purpose: the design refuses to sell the change as a speed gain, because {@code getChunk} is + * reached on a chunk change rather than per block and {@code ChunkCache} memoises in between. + *

+ * + *

Why this measures chunk 4/7 and not chunk 0/0

+ *

+ * {@code CoordConversion#chunkIndex} is {@code ((long) chunkX << 32) | (chunkZ & 0xffffffffL)}, so + * the index of the origin chunk is {@code 0L} — the one value in the whole world that + * {@code Long#valueOf} hands out of its cache instead of allocating. A loop over chunk 0/0 therefore + * reports zero bytes against the boxed map as well, and would pass before this task did anything at + * all. The position below has a non-zero {@code chunkX}, so its index is above {@code 2^32} and no + * autobox cache of any size can reach it. Whoever moves this position moves the point of the test. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ExtendWith(MicrotusExtension.class) +@DisplayName("What a chunk lookup allocates") +class ChunkLookupAllocationTest { + + /** + * How many lookups the measurement performs. + */ + private static final int LOOKUPS = 500_000; + + /** + * How many lookups run before the measurement, so the loop is compiled. + */ + private static final int WARMUP = 100_000; + + /** + * The X of the measured position, non-zero so that its chunk index is outside every autobox cache. + */ + private static final int CHUNK_X = 4; + + /** + * The Z of the measured position. + */ + private static final int CHUNK_Z = 7; + + /** + * Where the looked up chunk is published, so no compiler may drop the lookup. + */ + private static volatile Object sink; + + /** + * Performs the given number of lookups and reports what the calling thread allocated. + * + * @param registry the registry to look up in + * @param times how many lookups to perform + * @return the bytes the calling thread allocated during the loop + */ + private static long allocatedWhileLookingUp(ChunkRegistry registry, int times) { + final ThreadMXBean threads = (ThreadMXBean) ManagementFactory.getThreadMXBean(); + final long before = threads.getCurrentThreadAllocatedBytes(); + + for (int index = 0; index < times; index++) { + sink = registry.chunk(CHUNK_X, CHUNK_Z); + } + return threads.getCurrentThreadAllocatedBytes() - before; + } + + @Test + @DisplayName("allocates nothing at all") + void testALookupIsAllocationFree(Env env) { + final ThreadMXBean threads = (ThreadMXBean) ManagementFactory.getThreadMXBean(); + assumeTrue(threads.isThreadAllocatedMemorySupported(), + "this JVM cannot report per thread allocation, so the question cannot be answered here"); + threads.setThreadAllocatedMemoryEnabled(true); + + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + instance.loadChunk(CHUNK_X, CHUNK_Z).join(); + final ChunkRegistry registry = instance.registry(); + assertNotNull(registry.chunk(CHUNK_X, CHUNK_Z), + "the position has to carry a chunk, or this loop measures a miss"); + + allocatedWhileLookingUp(registry, WARMUP); + final long allocated = allocatedWhileLookingUp(registry, LOOKUPS); + + System.out.printf("chunk lookups: %,d -> %,d B (%.3f B each)%n", + LOOKUPS, allocated, (double) allocated / LOOKUPS); + assertTrue(allocated < LOOKUPS, "a chunk lookup allocated " + allocated + " B over " + LOOKUPS + + " lookups, which is more than a byte each: the index is still being boxed"); + } +} diff --git a/falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkMapLockOnMissTest.java b/falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkMapLockOnMissTest.java new file mode 100644 index 0000000..9312eda --- /dev/null +++ b/falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkMapLockOnMissTest.java @@ -0,0 +1,182 @@ +package net.onelitefeather.falco.instance; + +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.Timeout; +import space.vectrix.flare.fastutil.Long2ObjectSyncMap; + +import java.util.concurrent.CountDownLatch; +import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicReference; +import java.util.function.LongFunction; + +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Pins the one sentence the javadoc of {@code ChunkRegistry#chunks} is not allowed to get wrong: a + * lookup in {@code Long2ObjectSyncMap} is lock free when it hits the read map and takes a monitor + * when it does not. + *

+ * That field javadoc used to say "lookups take no lock", full stop, and that reading of the library + * is false. {@code Long2ObjectSyncMapImpl#getEntry} reads the read map without a lock, and when that + * returns null while the map is amended it enters {@code synchronized(this.lock)} to consult the + * dirty map. All of that is a property of a dependency rather than of this repository, which is + * exactly why prose about it rots in silence: nothing here breaks when flare changes or when a + * Minestom bump drags in a different version of it. This test is what breaks. + *

+ * + *

Why the monitor is held through a mapping function rather than taken from the field

+ *

+ * The monitor is a private field of the implementation and this project does not use reflection, so + * the lock is taken the way the library itself hands it out. {@code computeIfAbsent} on a key that is + * in neither map runs its mapping function inside {@code synchronized(this.lock)}, so a + * function which parks there holds the map's monitor for as long as it is parked, through public API + * and nothing else. {@code CountDownLatch#await} parks on a queue rather than on the monitor, so + * unlike {@code Object#wait} it does not hand the monitor back while it waits. + *

+ * + *

Why the setup is three lines and why none of them may be dropped

+ *

+ * The arrangement is the fragile part of a test like this, because the two internal maps are not + * observable from outside and a setup which looks like it arranges something can be arranging + * nothing. Two things have to be true at the moment the probes run: the hit key has to be in the read + * map, and the map has to be amended so that a miss reaches the slow path. + *

+ *

+ * The first needs the {@code put} and then the {@code size()}, because a {@code put} of a new key + * writes the dirty map and only a promotion moves it across; {@code size()} calls the library's + * {@code promote()} and is the shortest public way to force one. The second needs nothing at all, + * and that is worth stating rather than papering over with a second {@code put}: the holder's own + * {@code computeIfAbsent} runs {@code dirtyLocked()} and sets {@code amended} before it calls the + * mapping function, so by the time the monitor is held the miss path is armed by construction. + *

+ *

+ * There is deliberately no probing of the map before the holder starts. A lookup which misses while + * the map is amended counts a miss and promotes once the misses reach the size of the dirty map, so + * a "check the arrangement first" assertion would repair a broken arrangement on its way past and + * leave a test that passes no matter which setup line is removed. That is not hypothetical: it is + * what the first version of this class did, and two of the three mutations below survived it. What + * the probes return is therefore asserted after they return, where reading it costs nothing. + *

+ * + *

The three mutations this has to fail against

+ *

+ * Point the miss probe at the promoted key, and the blocked assertion has to fail. Drop the + * {@code size()}, so the promoted key stays in the dirty map, and the hit probe has to block. Let the + * mapping function return without parking, so no monitor is held, and the blocked assertion has to + * fail again. All three were run. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@DisplayName("What a lookup in the chunk map locks") +class ChunkMapLockOnMissTest { + + /** + * A key which is promoted into the read map before the measurement, so its lookup is a hit. + */ + private static final long PROMOTED = 40L; + + /** + * A key which is never written, so a lookup of it finds neither map and is the miss under test. + */ + private static final long ABSENT = 42L; + + /** + * A key the holder thread computes, so its mapping function runs while the monitor is held. + */ + private static final long HOLDER = 43L; + + /** + * How long a lookup is given to prove that it is blocked. A lookup which takes no lock returns in + * microseconds, so this window only has to be wide enough that a scheduling hiccup cannot be + * mistaken for a monitor. + */ + private static final long BLOCKED_WINDOW_MILLIS = 300L; + + /** + * How long a lookup is given to prove that it completed. + */ + private static final long COMPLETION_TIMEOUT_SECONDS = 5L; + + /** + * Starts a thread which looks the given key up, records what it got and reports when it returned. + * + * @param map the map to look up in + * @param key the key to look up + * @param result where the returned value is recorded + * @param done counted down once the lookup has returned + */ + private static void probe(Long2ObjectSyncMap map, long key, + AtomicReference result, CountDownLatch done) { + final Thread thread = new Thread(() -> { + result.set(map.get(key)); + done.countDown(); + }, "probe-" + key); + thread.setDaemon(true); + thread.start(); + } + + @Test + @Timeout(30) + @DisplayName("a hit walks past a held monitor and a miss waits for it") + void testAMissTakesTheMonitorAndAHitDoesNot() throws InterruptedException { + final Long2ObjectSyncMap map = Long2ObjectSyncMap.hashmap(); + final Object value = new Object(); + + map.put(PROMOTED, value); + map.size(); + + final CountDownLatch entered = new CountDownLatch(1); + final CountDownLatch release = new CountDownLatch(1); + final LongFunction holdTheMonitor = key -> { + entered.countDown(); + try { + release.await(); + } catch (InterruptedException exception) { + Thread.currentThread().interrupt(); + } + return value; + }; + + final Thread holder = new Thread(() -> map.computeIfAbsent(HOLDER, holdTheMonitor), "monitor-holder"); + holder.setDaemon(true); + holder.start(); + + final AtomicReference hitResult = new AtomicReference<>(); + final AtomicReference missResult = new AtomicReference<>(); + final CountDownLatch hitDone = new CountDownLatch(1); + final CountDownLatch missDone = new CountDownLatch(1); + try { + assertTrue(entered.await(COMPLETION_TIMEOUT_SECONDS, TimeUnit.SECONDS), + "the mapping function never ran, so no monitor was ever held and nothing below is a measurement"); + + probe(map, PROMOTED, hitResult, hitDone); + assertTrue(hitDone.await(COMPLETION_TIMEOUT_SECONDS, TimeUnit.SECONDS), + "a lookup of the promoted key blocked behind the monitor, so that key was not in the read map" + + " and the arrangement of this test is broken"); + + probe(map, ABSENT, missResult, missDone); + assertFalse(missDone.await(BLOCKED_WINDOW_MILLIS, TimeUnit.MILLISECONDS), + "a lookup of an absent key returned while the map's monitor was held, so it took no lock:" + + " the field javadoc of ChunkRegistry#chunks may say lookups are lock free again"); + } finally { + release.countDown(); + } + + holder.join(TimeUnit.SECONDS.toMillis(COMPLETION_TIMEOUT_SECONDS)); + assertTrue(missDone.await(COMPLETION_TIMEOUT_SECONDS, TimeUnit.SECONDS), + "the blocked lookup never returned after the monitor was released, so a monitor is not what it waited for"); + + assertNotNull(hitResult.get(), "the unblocked lookup returned null, so it was a miss which took no lock" + + " rather than the read map hit this arm claims to be"); + assertSame(value, hitResult.get(), "the unblocked lookup returned a foreign value"); + assertNull(missResult.get(), "the blocked lookup found a value, so the key it probed was not absent"); + } +} diff --git a/falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkRegistryTest.java b/falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkRegistryTest.java new file mode 100644 index 0000000..78cde71 --- /dev/null +++ b/falco-instance/src/test/java/net/onelitefeather/falco/instance/ChunkRegistryTest.java @@ -0,0 +1,206 @@ +package net.onelitefeather.falco.instance; + +import net.minestom.server.coordinate.CoordConversion; +import net.minestom.server.instance.Chunk; +import net.minestom.server.world.DimensionType; +import net.minestom.testing.Env; +import net.minestom.testing.extension.MicrotusExtension; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; + +import java.util.UUID; +import java.util.concurrent.CompletableFuture; +import java.util.concurrent.atomic.AtomicInteger; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertInstanceOf; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Drives every transition of a chunk position directly, without a loader and without a load. + *

+ * This is half of US-3.02. The transitions used to be three {@code private} methods of a class of + * 1 722 lines and could only be reached by loading a chunk through a loader, which meant that a test + * of the publish had to be a test of the whole load path and could never cover the case where a + * publish is refused — that case needs an unload to interleave with a load, which is exactly what a + * full load path makes impossible to arrange. + *

+ *

+ * Two of the cases below drive a step which throws. They are not there because throwing is supported + * — {@link ChunkRegistry} forbids it — but because the state such a step leaves behind is written + * down in that contract, and a documented failure mode which nothing measures is a claim rather than + * a fact. + *

+ * + * @author TheMeinerLP + * @version 1.1.0 + * @since 0.4.0 + */ +@ExtendWith(MicrotusExtension.class) +@DisplayName("The registry of chunk positions") +class ChunkRegistryTest { + + /** + * The position every case works on. + */ + private static final long INDEX = CoordConversion.chunkIndex(0, 0); + + /** + * Creates a registered instance to build chunks for. + * + * @param env the environment which provides the server process + * @return the registered instance + */ + private static FalcoInstance registered(Env env) { + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + return instance; + } + + @Test + @DisplayName("hands the first caller the slot and every later one the same future") + void testTheFirstCallerOwnsTheSlot(Env env) { + registered(env); + final ChunkRegistry registry = new ChunkRegistry(); + final CompletableFuture first = new CompletableFuture<>(); + final CompletableFuture second = new CompletableFuture<>(); + + assertInstanceOf(ChunkRegistry.LoadSlot.Claimed.class, registry.acquire(INDEX, first)); + final ChunkRegistry.LoadSlot slot = registry.acquire(INDEX, second); + + assertSame(first, assertInstanceOf(ChunkRegistry.LoadSlot.Running.class, slot).future(), + "the second caller has to receive the future of the first, not one of its own"); + } + + @Test + @DisplayName("hands back the published chunk instead of a slot") + void testAPublishedChunkEndsTheLoad(Env env) { + final FalcoInstance instance = registered(env); + final ChunkRegistry registry = new ChunkRegistry(); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + final CompletableFuture own = new CompletableFuture<>(); + registry.acquire(INDEX, own); + final AtomicInteger insideLock = new AtomicInteger(); + + assertTrue(registry.publish(INDEX, chunk, own, published -> insideLock.incrementAndGet())); + + assertEquals(1, insideLock.get(), "the step handed in has to run exactly once, while the position is held"); + assertSame(chunk, registry.chunk(INDEX)); + assertEquals(0, registry.loading(), "a published chunk releases the slot of its position"); + assertSame(chunk, assertInstanceOf(ChunkRegistry.LoadSlot.Loaded.class, + registry.acquire(INDEX, new CompletableFuture<>())).chunk()); + } + + @Test + @DisplayName("refuses to publish a chunk whose load was claimed") + void testAClaimedLoadCannotPublish(Env env) { + final FalcoInstance instance = registered(env); + final ChunkRegistry registry = new ChunkRegistry(); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + final CompletableFuture own = new CompletableFuture<>(); + registry.acquire(INDEX, own); + final AtomicInteger insideLock = new AtomicInteger(); + + assertSame(own, registry.discard(INDEX)); + assertFalse(registry.publish(INDEX, chunk, own, published -> insideLock.incrementAndGet())); + + assertEquals(0, insideLock.get(), "a refused publish must not run the step it was given"); + assertNull(registry.chunk(INDEX), "a refused publish leaves the position empty"); + } + + @Test + @DisplayName("removes a chunk once and reports the second attempt as a no-op") + void testRemovingTwice(Env env) { + final FalcoInstance instance = registered(env); + final ChunkRegistry registry = new ChunkRegistry(); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + final CompletableFuture own = new CompletableFuture<>(); + registry.acquire(INDEX, own); + registry.publish(INDEX, chunk, own, published -> { + }); + final AtomicInteger insideLock = new AtomicInteger(); + + assertTrue(registry.remove(INDEX, chunk, removed -> insideLock.incrementAndGet())); + assertFalse(registry.remove(INDEX, chunk, removed -> insideLock.incrementAndGet())); + + assertEquals(1, insideLock.get(), "the step handed in runs for the removal that happened and no other"); + assertTrue(registry.idle()); + } + + @Test + @DisplayName("refuses to remove a chunk which is not the one at that position") + void testRemovingAStrangerDoesNothing(Env env) { + final FalcoInstance instance = registered(env); + final ChunkRegistry registry = new ChunkRegistry(); + final FalcoChunk resident = new FalcoChunk(instance, 0, 0); + final FalcoChunk stranger = new FalcoChunk(instance, 0, 0); + final CompletableFuture own = new CompletableFuture<>(); + registry.acquire(INDEX, own); + registry.publish(INDEX, resident, own, published -> { + }); + + assertFalse(registry.remove(INDEX, stranger, removed -> { + })); + assertSame(resident, registry.chunk(INDEX), "the chunk that is actually there has to survive"); + } + + @Test + @DisplayName("leaves a position loaded and loading at once when a publish step throws") + void testAThrowingPublishStepWedgesThePosition(Env env) { + final FalcoInstance instance = registered(env); + final ChunkRegistry registry = new ChunkRegistry(); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + final CompletableFuture own = new CompletableFuture<>(); + registry.acquire(INDEX, own); + + assertThrows(IllegalStateException.class, () -> registry.publish(INDEX, chunk, own, published -> { + throw new IllegalStateException("the step of a caller failed"); + }), "a step which throws has to reach the caller rather than be swallowed"); + + assertSame(chunk, registry.chunk(INDEX), + "the chunk map is written before the step runs, so the chunk stays at its position"); + assertEquals(1, registry.loading(), + "compute leaves its own mapping alone when the step throws, so the load stays claimed"); + assertSame(own, assertInstanceOf(ChunkRegistry.LoadSlot.Running.class, + registry.acquire(INDEX, new CompletableFuture<>())).future(), + "every later caller is handed the future of a load which nobody will complete"); + } + + @Test + @DisplayName("keeps the removal when the remove step throws") + void testAThrowingRemoveStepKeepsTheRemoval(Env env) { + final FalcoInstance instance = registered(env); + final ChunkRegistry registry = new ChunkRegistry(); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + final CompletableFuture own = new CompletableFuture<>(); + registry.acquire(INDEX, own); + registry.publish(INDEX, chunk, own, published -> { + }); + + assertThrows(IllegalStateException.class, () -> registry.remove(INDEX, chunk, removed -> { + throw new IllegalStateException("the step of a caller failed"); + }), "a step which throws has to reach the caller rather than be swallowed"); + + assertNull(registry.chunk(INDEX), + "the chunk map is written before the step runs, so the removal stands"); + assertTrue(registry.idle(), "nothing of the position is left behind in either map"); + } + + @Test + @DisplayName("hands out the loading positions so a shutdown can claim them") + void testLoadingPositionsAreVisible(Env env) { + registered(env); + final ChunkRegistry registry = new ChunkRegistry(); + registry.acquire(CoordConversion.chunkIndex(1, 1), new CompletableFuture<>()); + registry.acquire(CoordConversion.chunkIndex(2, 2), new CompletableFuture<>()); + + assertEquals(2, registry.loadingPositions().size()); + assertEquals(2, registry.loading()); + assertFalse(registry.idle()); + } +} diff --git a/falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoChunkEquivalenceTest.java b/falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoChunkEquivalenceTest.java new file mode 100644 index 0000000..8e3375b --- /dev/null +++ b/falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoChunkEquivalenceTest.java @@ -0,0 +1,112 @@ +package net.onelitefeather.falco.instance; + +import net.minestom.server.MinecraftServer; +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.DynamicChunk; +import net.minestom.server.instance.Instance; +import net.minestom.server.instance.block.Block; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; + +import java.util.Random; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Pins down that {@link FalcoChunk} holds the same block at every position as {@code DynamicChunk}, + * the chunk Minestom ships with. + *

+ * This is the equivalence US-1.03 promises and NFR-004 requires evidence for: a bridge chunk that + * merely compiles against {@code Chunk} is not enough, since the storage behind it was rewritten from + * scratch in Task 3. The two chunks are filled through the very same {@code fill} routine from the + * very same seed and then read back position by position, so a divergence names the exact coordinate + * and the exact fill it happened under instead of a vague "the chunks disagree somewhere". + *

+ *

+ * The parameter axis is the number of distinct block states a chunk is filled with, from a single + * state up to 1024. A palette-backed storage bit-packs its entries only as wide as the number of + * distinct states demands, so a bug tied to a particular bit width would hide at one end of this axis + * and show only at the other. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@DisplayName("A Falco chunk against the chunk of Minestom") +class FalcoChunkEquivalenceTest { + + private static final long SEED = 20260801L; + private static final int MIN_Y = -64; + private static final int HEIGHT = 384; + + private static Instance instance; + + @BeforeAll + static void server() { + if (MinecraftServer.process() == null) { + MinecraftServer.init(); + } + instance = MinecraftServer.getInstanceManager().createInstanceContainer(); + } + + private static void fill(Chunk chunk, int distinctStates, long seed) { + final Random random = new Random(seed); + final Block[] blocks = new Block[distinctStates]; + + for (int index = 0; index < distinctStates; index++) { + blocks[index] = Block.fromStateId(index + 1); + } + chunk.lockWriteLock(); + try { + for (int y = MIN_Y; y < MIN_Y + HEIGHT; y++) { + for (int z = 0; z < 16; z++) { + for (int x = 0; x < 16; x++) { + chunk.setBlock(x, y, z, blocks[random.nextInt(distinctStates)]); + } + } + } + } finally { + chunk.unlockWriteLock(); + } + } + + @ParameterizedTest(name = "{0} distinct states") + @ValueSource(ints = {1, 2, 16, 64, 256, 1024}) + @DisplayName("holds the same block at every position") + void testEveryPositionAgrees(int distinctStates) { + final Chunk minestom = new DynamicChunk(instance, 0, 0); + final Chunk falco = new FalcoChunk(instance, 0, 0); + + fill(minestom, distinctStates, SEED); + fill(falco, distinctStates, SEED); + + int nonAir = 0; + + minestom.lockReadLock(); + falco.lockReadLock(); + try { + for (int y = MIN_Y; y < MIN_Y + HEIGHT; y++) { + for (int z = 0; z < 16; z++) { + for (int x = 0; x < 16; x++) { + final Block expected = minestom.getBlock(x, y, z); + final Block actual = falco.getBlock(x, y, z); + + assertEquals(expected, actual, + "block at " + x + "/" + y + "/" + z + " with " + distinctStates + " states"); + if (!expected.isAir()) { + nonAir++; + } + } + } + } + } finally { + falco.unlockReadLock(); + minestom.unlockReadLock(); + } + assertTrue(nonAir > 0, "the fixture wrote nothing, so this run compared two empty chunks"); + } +} diff --git a/falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoChunkInContainerTest.java b/falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoChunkInContainerTest.java new file mode 100644 index 0000000..bfb6a7a --- /dev/null +++ b/falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoChunkInContainerTest.java @@ -0,0 +1,44 @@ +package net.onelitefeather.falco.instance; + +import net.minestom.server.MinecraftServer; +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.InstanceContainer; +import net.minestom.server.instance.block.Block; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertInstanceOf; + +@DisplayName("A Falco chunk owned by a plain InstanceContainer") +class FalcoChunkInContainerTest { + + @BeforeAll + static void server() { + if (MinecraftServer.process() == null) { + MinecraftServer.init(); + } + } + + @Test + @DisplayName("is created by the container, survives a write and unloads cleanly") + void testContainerOwnsTheChunk() { + final InstanceContainer container = MinecraftServer.getInstanceManager().createInstanceContainer(); + + container.setChunkSupplier(FalcoChunk::new); + + final Chunk chunk = container.loadChunk(0, 0).join(); + + assertInstanceOf(FalcoChunk.class, chunk, "the container has to use the supplier it was given"); + + container.setBlock(0, 0, 0, Block.STONE); + assertEquals(Block.STONE, container.getBlock(0, 0, 0)); + + container.unloadChunk(chunk); + assertFalse(chunk.isLoaded(), "the container reaches the protected unload hook itself"); + + MinecraftServer.getInstanceManager().unregisterInstance(container); + } +} diff --git a/falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoChunkTest.java b/falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoChunkTest.java index 74bef33..65fc9b3 100644 --- a/falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoChunkTest.java +++ b/falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoChunkTest.java @@ -1,19 +1,25 @@ package net.onelitefeather.falco.instance; +import net.kyori.adventure.key.Key; import net.minestom.server.instance.Chunk; import net.minestom.server.instance.block.Block; +import net.minestom.server.instance.block.BlockHandler; import net.minestom.server.world.DimensionType; import net.minestom.testing.Env; import net.minestom.testing.extension.MicrotusExtension; +import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.extension.ExtendWith; import java.util.UUID; +import java.util.concurrent.atomic.AtomicInteger; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertFalse; import static org.junit.jupiter.api.Assertions.assertInstanceOf; +import static org.junit.jupiter.api.Assertions.assertNotNull; import static org.junit.jupiter.api.Assertions.assertNotSame; +import static org.junit.jupiter.api.Assertions.assertSame; import static org.junit.jupiter.api.Assertions.assertTrue; /** @@ -25,8 +31,19 @@ * operations Minestom performs on a chunk. *

* + *

+ * The heightmap cases are here for a different reason: they are the only place where the claim that + * a chunk builds a heightmap when it is asked and not before can be observed at all. + *

+ * + *

+ * The ticking cases are here for a third reason: they characterise what a tick reaches, so that the + * bookkeeping which decides that can be replaced without the replacement being free to change the + * answer. + *

+ * * @author TheMeinerLP - * @version 1.0.0 + * @version 1.3.1 * @since 0.1.0 */ @ExtendWith(MicrotusExtension.class) @@ -99,4 +116,300 @@ void testACopyIsAFalcoChunkAgain(Env env) { copy.unlockReadLock(); } } + + /** + * States the property the on-demand heightmaps exist for, in the only way it can be stated. + *

+ * A heightmap is a {@code short[256]} plus its carrier, and the two of them together weigh + * {@code 1 120} bytes — more than the {@code 840} a fresh {@link FalcoChunk} retains in total + * now that it builds neither until it is asked. In a fresh {@code DynamicChunk}, whose sections + * are real, the same {@code 1 120} bytes are the second largest post after those sections. The + * conditions those figures were measured under are on {@link FalcoChunk#motionBlockingHeightmap()}, + * and the measurement itself is {@code ChunkFootprintTest}, not this case: nothing here weighs + * anything. The claim this case makes is not that heightmaps are cheaper but that a chunk + * which is only constructed and read has none, so the case walks exactly that path: construct, + * read one block, and only then ask. The read is in the middle rather than at the end because a + * block read is what a chunk loader and a light computation do, and it is the path on which the + * saving is supposed to survive. + *

+ * + * @param env the environment which provides the server process + */ + @Test + @DisplayName("builds no heightmap until something asks for one") + void testHeightmapsAreBuiltOnDemand(Env env) { + final FalcoChunk chunk = new FalcoChunk(registered(env), 0, 0); + + assertFalse(chunk.hasHeightmaps(), "a chunk that was only constructed needs no heightmap"); + + chunk.lockReadLock(); + try { + chunk.getBlock(0, 0, 0); + } finally { + chunk.unlockReadLock(); + } + assertFalse(chunk.hasHeightmaps(), "a block read does not need a heightmap either"); + + assertNotNull(chunk.motionBlockingHeightmap()); + assertTrue(chunk.hasHeightmaps()); + } + + /** + * Holds the double-checked lock to its second half. + *

+ * The first half — that nothing is built too early — is the case above. This one is the other + * direction: an accessor which built a heightmap and forgot to store it would satisfy every + * caller and still be wrong, because the heights a chunk accumulated through + * {@code Heightmap#refresh(int, int, int, Block)} would be thrown away on the next call and the + * chunk would answer from a map that was never refreshed. + *

+ * + * @param env the environment which provides the server process + */ + @Test + @DisplayName("hands out the same heightmap on every call") + void testTheHeightmapIsBuiltOnce(Env env) { + final FalcoChunk chunk = new FalcoChunk(registered(env), 0, 0); + + assertSame(chunk.motionBlockingHeightmap(), chunk.motionBlockingHeightmap()); + assertSame(chunk.worldSurfaceHeightmap(), chunk.worldSurfaceHeightmap()); + assertNotSame(chunk.motionBlockingHeightmap(), chunk.worldSurfaceHeightmap()); + } + + /** + * Builds a handler which counts the ticks it receives without ever asking for one. + *

+ * The counterpart of {@link #tickingHandler(AtomicInteger)}, and the only way to observe a tick + * that should not have happened. It counts in {@code tick} precisely because it must never be + * called, so a chunk which ticks it leaves the evidence itself. + *

+ * + * @param ticks the counter which is incremented once per tick, and which must stay at zero + * @return a handler which is not tickable + */ + private static BlockHandler quietHandler(AtomicInteger ticks) { + return new BlockHandler() { + + @Override + public Key getKey() { + return Key.key("falco", "quiet"); + } + + @Override + public void tick(Tick tick) { + ticks.incrementAndGet(); + } + }; + } + + /** + * Builds a handler which asks to be ticked and counts the ticks it receives. + *

+ * A counting handler is the only way the cases below can observe ticking at all: whether a chunk + * ticks a block is not readable from the chunk, it is only visible in whether the handler of that + * block ran. + *

+ * + * @param ticks the counter which is incremented once per tick + * @return a tickable handler + */ + private static BlockHandler tickingHandler(AtomicInteger ticks) { + return new BlockHandler() { + + @Override + public Key getKey() { + return Key.key("falco", "tickable"); + } + + @Override + public boolean isTickable() { + return true; + } + + @Override + public void tick(Tick tick) { + ticks.incrementAndGet(); + } + }; + } + + /** + * Pins which blocks a tick reaches, in both directions. + *

+ * This is a characterisation case rather than a red one: the behaviour already exists, and it is + * written down so that the bookkeeping behind it can be replaced without the replacement being + * able to change what a tick does. The second half is the half that can actually break — a chunk + * which only ever learns that a block became tickable, and never that one stopped being tickable, + * passes the first assertion and keeps ticking a block that is no longer there. + *

+ * + * @param env the environment which provides the server process + */ + @Test + @DisplayName("ticks a tickable handler and stops ticking it when it is replaced") + void testTickReachesOnlyTickableBlocks(Env env) { + final FalcoInstance instance = registered(env); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + final AtomicInteger ticks = new AtomicInteger(); + + chunk.lockWriteLock(); + try { + chunk.setBlock(0, 0, 0, Block.STONE.withHandler(tickingHandler(ticks))); + } finally { + chunk.unlockWriteLock(); + } + chunk.tick(0L); + assertEquals(1, ticks.get()); + + chunk.lockWriteLock(); + try { + chunk.setBlock(0, 0, 0, Block.STONE); + } finally { + chunk.unlockWriteLock(); + } + chunk.tick(0L); + assertEquals(1, ticks.get(), "a block that was replaced must stop being ticked"); + } + + /** + * Pins that a copy of a chunk keeps ticking what the original ticked. + * + * @param env the environment which provides the server process + */ + @Test + @DisplayName("carries the tickable blocks of a chunk into its copy") + void testCopyKeepsTicking(Env env) { + final FalcoInstance instance = registered(env); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + final AtomicInteger ticks = new AtomicInteger(); + + chunk.lockWriteLock(); + try { + chunk.setBlock(0, 0, 0, Block.STONE.withHandler(tickingHandler(ticks))); + } finally { + chunk.unlockWriteLock(); + } + chunk.lockReadLock(); + final Chunk copy; + try { + copy = chunk.copy(instance, 1, 1); + } finally { + chunk.unlockReadLock(); + } + copy.tick(0L); + assertEquals(1, ticks.get(), + "DynamicChunk#copy carries only the entries, which stops a copied chunk from ticking; " + + "that omission was corrected before the storage moved and stays corrected"); + } + + /** + * Holds the tickable counter to being a count and not a flag. + *

+ * The two cases above cannot do it. Since the tick walks the entries and skips what is not + * tickable, a counter that is merely too high changes nothing a caller can observe — it only + * costs a walk. The direction that is observable is a counter that is too low: it makes the tick + * take its early exit while a tickable block is still there, and that block silently stops + * ticking. That is the failure this case exists for, and it is the failure the map this counter + * replaced could not have. + *

+ *

+ * Two blocks, because one is not enough to tell a count from a flag: a chunk which stores whether + * it has any tickable block rather than how many gets the first block right and drops the second + * the moment the first one leaves. + *

+ * + * @param env the environment which provides the server process + */ + @Test + @DisplayName("keeps ticking the tickable blocks that are left when one of them leaves") + void testOneBlockLeavingDoesNotSilenceTheOthers(Env env) { + final FalcoInstance instance = registered(env); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + final AtomicInteger first = new AtomicInteger(); + final AtomicInteger second = new AtomicInteger(); + + chunk.lockWriteLock(); + try { + chunk.setBlock(0, 0, 0, Block.STONE.withHandler(tickingHandler(first))); + chunk.setBlock(1, 0, 0, Block.STONE.withHandler(tickingHandler(second))); + chunk.setBlock(0, 0, 0, Block.STONE); + } finally { + chunk.unlockWriteLock(); + } + chunk.tick(0L); + + assertEquals(0, first.get(), "the block that was replaced must not tick"); + assertEquals(1, second.get(), "the block that stayed must still tick"); + } + + /** + * Holds the counter to never going below the truth on the way up. + *

+ * A write which was never tickable and is still not tickable must leave the counter alone. One + * that pays a decrement for every such write drives the counter negative on an ordinary chunk + * full of ordinary blocks, and the tickable block placed afterwards is then paid for out of that + * debt instead of lifting the counter off zero — the chunk takes its early exit and the block + * never ticks. + *

+ *

+ * Exactly one plain write, and not two, because the early exit tests for zero rather than for a + * non-positive count: after two plain writes such a counter would sit at {@code -1} and the tick + * would still walk, so the defect would pass unnoticed. One plain write followed by one tickable + * write is the arrangement that lands the counter back on zero with a tickable block in the + * chunk, and it is the only arrangement in which this defect is visible from the outside at all. + *

+ * + * @param env the environment which provides the server process + */ + @Test + @DisplayName("ticks a tickable block placed after a plain one") + void testPlainWritesDoNotOwePastTheirTurn(Env env) { + final FalcoInstance instance = registered(env); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + final AtomicInteger ticks = new AtomicInteger(); + + chunk.lockWriteLock(); + try { + chunk.setBlock(0, 0, 0, Block.STONE); + chunk.setBlock(1, 0, 0, Block.STONE.withHandler(tickingHandler(ticks))); + } finally { + chunk.unlockWriteLock(); + } + chunk.tick(0L); + + assertEquals(1, ticks.get(), "a tickable block must tick regardless of what was written before it"); + } + + /** + * Holds the tick to the blocks which asked for it. + *

+ * This is the case the second map used to make impossible. That map held only tickable blocks, so + * walking it could not reach anything else; the walk now goes over the entries, which hold every + * block worth keeping as an object, and the only thing between a block entity that never asked to + * be ticked and a tick is the filter inside the loop. A filter is easier to lose than a map is, + * so what it does is written down here rather than left to the shape of the data. + *

+ * + * @param env the environment which provides the server process + */ + @Test + @DisplayName("does not tick a handler which did not ask to be ticked") + void testTickSkipsHandlersThatAreNotTickable(Env env) { + final FalcoInstance instance = registered(env); + final FalcoChunk chunk = new FalcoChunk(instance, 0, 0); + final AtomicInteger tickable = new AtomicInteger(); + final AtomicInteger quiet = new AtomicInteger(); + + chunk.lockWriteLock(); + try { + chunk.setBlock(0, 0, 0, Block.STONE.withHandler(tickingHandler(tickable))); + chunk.setBlock(1, 0, 0, Block.STONE.withHandler(quietHandler(quiet))); + } finally { + chunk.unlockWriteLock(); + } + chunk.tick(0L); + + assertEquals(1, tickable.get(), "the handler which asked to be ticked must be ticked"); + assertEquals(0, quiet.get(), "a handler which is not tickable must not be ticked"); + } } diff --git a/falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoInstanceBlockWriteTest.java b/falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoInstanceBlockWriteTest.java new file mode 100644 index 0000000..39e505a --- /dev/null +++ b/falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoInstanceBlockWriteTest.java @@ -0,0 +1,387 @@ +package net.onelitefeather.falco.instance; + +import net.kyori.adventure.key.Key; +import net.minestom.server.MinecraftServer; +import net.minestom.server.coordinate.BlockVec; +import net.minestom.server.coordinate.Pos; +import net.minestom.server.coordinate.Vec; +import net.minestom.server.entity.PlayerHand; +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.block.Block; +import net.minestom.server.instance.block.BlockFace; +import net.minestom.server.instance.block.BlockHandler; +import net.minestom.server.instance.block.rule.BlockPlacementRule; +import net.minestom.server.item.ItemStack; +import net.minestom.server.item.Material; +import net.minestom.server.world.DimensionType; +import net.minestom.testing.Env; +import net.minestom.testing.extension.MicrotusExtension; +import org.jetbrains.annotations.Nullable; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; + +import java.util.UUID; +import java.util.concurrent.atomic.AtomicInteger; +import java.util.concurrent.atomic.AtomicReference; +import java.util.function.Consumer; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNotEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Pins what a block write through {@link FalcoInstance} does, before the code that does it moves. + *

+ * Every case here covers a path that had no test at all when this class was written: the placement + * entry point, the break entry point, the neighbour update that follows a write, the recursion guard + * that keeps a handler from destroying its own block forever, and the change timestamp. The plan of + * stage 3 moves all of them into {@code BlockWriter}, and a move can only be checked against + * behaviour somebody wrote down first. + *

+ * + * @author TheMeinerLP + * @version 1.1.0 + * @since 0.4.0 + */ +@ExtendWith(MicrotusExtension.class) +@DisplayName("A block write through a Falco instance") +class FalcoInstanceBlockWriteTest { + + /** + * The height every case writes at, well inside the overworld and away from both limits. + */ + private static final int Y = 64; + + /** + * A handler which counts how often a block carrying it reached a chunk, and may write back. + *

+ * Counting the calls of {@code onPlace} rather than reading the block back is what makes the + * recursion guard observable at all: the guard drops a second write of the same block to the same + * position, and a dropped write leaves the chunk holding exactly what a performed write would have + * left it holding. Only the number of times the chunk was actually written tells the two apart. + *

+ * + * @param writes the counter raised once per write which reached the chunk + * @param echo what the handler does with the placement it was told about, null to do nothing + */ + private record CountingHandler(AtomicInteger writes, + @Nullable Consumer echo) implements BlockHandler { + + @Override + public void onPlace(Placement placement) { + this.writes.incrementAndGet(); + if (this.echo != null) this.echo.accept(placement); + } + + @Override + public Key getKey() { + return Key.key("falco", "counting"); + } + } + + /** + * A placement rule which keeps the state it was asked about and answers with a fixed block. + *

+ * The rule of the placed block is the one branch of a write that reshapes the block before it + * reaches the chunk, and it is the only caller of the state builder. Answering with a block that + * differs from the placed one makes the branch observable in the chunk; keeping the state makes + * observable what the builder put into it, which no assertion on the chunk could show. + *

+ */ + private static final class RecordingRule extends BlockPlacementRule { + + /** + * The state of the last placement this rule was asked about, null until it was asked. + */ + private final AtomicReference lastState = new AtomicReference<>(); + + /** + * What every placement is answered with, null to cancel the placement. + */ + private final @Nullable Block result; + + /** + * Creates a rule for a block. + * + * @param block the block this rule answers for + * @param result the block every placement is answered with, null to cancel it + */ + private RecordingRule(Block block, @Nullable Block result) { + super(block); + this.result = result; + } + + @Override + public @Nullable Block blockPlace(PlacementState state) { + this.lastState.set(state); + return this.result; + } + } + + /** + * Creates a registered instance in the environment of the test. + * + * @param env the environment which provides the server process + * @return the registered instance + */ + private static FalcoInstance registered(Env env) { + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + return instance; + } + + @Test + @DisplayName("places a block through placeBlock and reports that it did") + void testPlaceBlockWritesTheBlock(Env env) { + final FalcoInstance instance = registered(env); + instance.loadChunk(0, 0).join(); + + final boolean placed = instance.placeBlock(new BlockHandler.Placement(Block.STONE, Block.AIR, + instance, new BlockVec(1, Y, 1)), true); + + assertTrue(placed, "a loaded chunk accepts a placement"); + assertEquals(Block.STONE, instance.getBlock(1, Y, 1)); + } + + @Test + @DisplayName("refuses a placement into a chunk which is not loaded") + void testPlaceBlockRefusesAnUnloadedChunk(Env env) { + final FalcoInstance instance = registered(env); + + final boolean placed = instance.placeBlock(new BlockHandler.Placement(Block.STONE, Block.AIR, + instance, new BlockVec(1, Y, 1)), true); + + assertFalse(placed, "there is no chunk at that position, so nothing can be placed"); + } + + @Test + @DisplayName("writes what the placement rule of the placed block decided, not what was placed") + void testAPlacementRuleDecidesTheWrittenBlock(Env env) { + final FalcoInstance instance = registered(env); + instance.loadChunk(0, 0).join(); + MinecraftServer.getBlockManager().registerBlockPlacementRule( + new RecordingRule(Block.SANDSTONE, Block.BRICKS)); + + final boolean placed = instance.placeBlock(new BlockHandler.Placement(Block.SANDSTONE, Block.AIR, + instance, new BlockVec(8, Y, 8)), true); + + assertTrue(placed, "a loaded chunk accepts a placement"); + assertEquals(Block.BRICKS, instance.getBlock(8, Y, 8), + "the block the rule answered with is the one that has to reach the chunk"); + } + + @Test + @DisplayName("leaves air behind when the placement rule cancels the placement") + void testACancellingPlacementRuleLeavesAir(Env env) { + final FalcoInstance instance = registered(env); + instance.loadChunk(0, 0).join(); + MinecraftServer.getBlockManager().registerBlockPlacementRule( + new RecordingRule(Block.OAK_PLANKS, null)); + + final boolean placed = instance.placeBlock(new BlockHandler.Placement(Block.OAK_PLANKS, Block.AIR, + instance, new BlockVec(9, Y, 9)), true); + + assertTrue(placed, "the placement was carried out, the rule only decided what it carried"); + assertEquals(Block.AIR, instance.getBlock(9, Y, 9), + "a rule which answers null cancels the placement, which leaves air rather than the placed block"); + } + + @Test + @DisplayName("hands a rule the position and the block of a placement which had no player") + void testAPlacementWithoutAPlayerCarriesNoPlayerState(Env env) { + final FalcoInstance instance = registered(env); + instance.loadChunk(0, 0).join(); + final RecordingRule rule = new RecordingRule(Block.COBBLESTONE, Block.COBBLESTONE); + MinecraftServer.getBlockManager().registerBlockPlacementRule(rule); + final BlockVec position = new BlockVec(10, Y, 10); + + instance.placeBlock(new BlockHandler.Placement(Block.COBBLESTONE, Block.AIR, instance, position), true); + + final BlockPlacementRule.PlacementState state = rule.lastState.get(); + assertNotNull(state, "the rule of the placed block has to be asked before the block is written"); + assertSame(instance, state.instance(), "the rule is asked about the instance the write goes to"); + assertEquals(Block.COBBLESTONE, state.block()); + assertEquals(position, state.placePosition()); + assertNull(state.blockFace(), "a placement without a player clicked no face"); + assertNull(state.cursorPosition(), "a placement without a player has no cursor"); + assertNull(state.playerPosition(), "a placement without a player has no player position"); + assertNull(state.usedItemStack(), "a placement without a player used no item"); + assertFalse(state.isPlayerShifting(), "a placement without a player is not shifting"); + } + + @Test + @DisplayName("hands a rule the face, the cursor and the player of a placement which had one") + void testAPlayerPlacementCarriesThePlayerIntoTheRule(Env env) { + final FalcoInstance instance = registered(env); + instance.loadChunk(0, 0).join(); + final RecordingRule rule = new RecordingRule(Block.MOSSY_COBBLESTONE, Block.SMOOTH_STONE); + MinecraftServer.getBlockManager().registerBlockPlacementRule(rule); + final var connection = env.createConnection(); + final var player = connection.connect(instance, new Pos(0, Y, 0)); + final ItemStack held = ItemStack.of(Material.DIAMOND); + player.setItemInMainHand(held); + player.setSneaking(true); + final BlockVec position = new BlockVec(11, Y, 11); + + instance.placeBlock(new BlockHandler.PlayerPlacement(Block.MOSSY_COBBLESTONE, Block.AIR, instance, position, + player, PlayerHand.MAIN, BlockFace.WEST, 0.25F, 0.5F, 0.75F), true); + + final BlockPlacementRule.PlacementState state = rule.lastState.get(); + assertNotNull(state, "the rule of the placed block has to be asked before the block is written"); + assertEquals(BlockFace.WEST, state.blockFace(), "the face the player clicked has to reach the rule"); + assertEquals(new Vec(0.25, 0.5, 0.75), state.cursorPosition(), + "the cursor of the player has to reach the rule"); + assertEquals(player.getPosition(), state.playerPosition(), + "the position of the player has to reach the rule"); + assertEquals(held, state.usedItemStack(), + "the item in the hand the placement names has to reach the rule"); + assertTrue(state.isPlayerShifting(), "a sneaking player has to reach the rule as shifting"); + assertEquals(Block.SMOOTH_STONE, instance.getBlock(position), + "the block the rule answered with is the one that has to reach the chunk"); + } + + @Test + @DisplayName("breaks a block and leaves air where it stood") + void testBreakBlockReplacesTheBlock(Env env) { + final FalcoInstance instance = registered(env); + instance.loadChunk(0, 0).join(); + instance.setBlock(1, Y, 1, Block.STONE); + final var connection = env.createConnection(); + final var player = connection.connect(instance, new Pos(0, Y, 0)); + + final boolean broken = instance.breakBlock(player, new BlockVec(1, Y, 1), BlockFace.TOP, true); + + assertTrue(broken, "a solid block in a loaded chunk can be broken"); + assertEquals(Block.AIR, instance.getBlock(1, Y, 1)); + } + + @Test + @DisplayName("refuses to break air and does not pretend it broke something") + void testBreakBlockRefusesAir(Env env) { + final FalcoInstance instance = registered(env); + instance.loadChunk(0, 0).join(); + final var connection = env.createConnection(); + final var player = connection.connect(instance, new Pos(0, Y, 0)); + + assertFalse(instance.breakBlock(player, new BlockVec(1, Y, 1), BlockFace.TOP, true), + "there is no block there, so the client is resent the chunk instead"); + } + + @Test + @DisplayName("lets a placement rule reshape the neighbour of a written block") + void testANeighbourReshapesItself(Env env) { + final FalcoInstance instance = registered(env); + instance.loadChunk(0, 0).join(); + final AtomicInteger updates = new AtomicInteger(); + MinecraftServer.getBlockManager().registerBlockPlacementRule(new BlockPlacementRule(Block.GLASS) { + + @Override + public Block blockUpdate(UpdateState state) { + updates.incrementAndGet(); + return Block.GLOWSTONE; + } + + @Override + public Block blockPlace(PlacementState state) { + return state.block(); + } + }); + instance.setBlock(2, Y, 1, Block.GLASS); + + instance.setBlock(1, Y, 1, Block.STONE, true); + + assertTrue(updates.get() > 0, "the neighbour of the written block has to be asked to reshape itself"); + assertEquals(Block.GLOWSTONE, instance.getBlock(2, Y, 1), + "what the rule returned has to end up in the chunk"); + } + + @Test + @DisplayName("does not run neighbour updates when the caller switched them off") + void testNeighbourUpdatesCanBeSwitchedOff(Env env) { + final FalcoInstance instance = registered(env); + instance.loadChunk(0, 0).join(); + final AtomicInteger updates = new AtomicInteger(); + MinecraftServer.getBlockManager().registerBlockPlacementRule(new BlockPlacementRule(Block.OAK_LEAVES) { + + @Override + public Block blockUpdate(UpdateState state) { + updates.incrementAndGet(); + return state.currentBlock(); + } + + @Override + public Block blockPlace(PlacementState state) { + return state.block(); + } + }); + instance.setBlock(4, Y, 1, Block.OAK_LEAVES); + + instance.setBlock(3, Y, 1, Block.STONE, false); + + assertEquals(0, updates.get(), "doBlockUpdates=false has to skip the neighbour pass entirely"); + } + + @Test + @DisplayName("stops a handler which writes its own block again from recursing") + void testTheRecursionGuardHolds(Env env) { + final FalcoInstance instance = registered(env); + instance.loadChunk(0, 0).join(); + final AtomicInteger writes = new AtomicInteger(); + final Block looping = Block.STONE.withHandler(new CountingHandler(writes, + placement -> instance.setBlock(placement.getBlockPosition(), placement.getBlock()))); + + instance.setBlock(5, Y, 5, looping); + + assertEquals(1, writes.get(), + "the second write of the same block to the same position has to be dropped by the guard"); + } + + @Test + @DisplayName("lets the same block be written again after the tick which cleared the guard") + void testTheGuardIsClearedByATick(Env env) { + final FalcoInstance instance = registered(env); + instance.loadChunk(0, 0).join(); + final AtomicInteger writes = new AtomicInteger(); + final Block counted = Block.STONE.withHandler(new CountingHandler(writes, null)); + + instance.setBlock(6, Y, 6, counted); + instance.setBlock(6, Y, 6, counted); + assertEquals(1, writes.get(), "the same block at the same position reaches the chunk once per tick"); + + instance.tick(System.currentTimeMillis()); + instance.setBlock(6, Y, 6, counted); + + assertEquals(2, writes.get(), + "the guard is scoped to one tick, so the same block can be written again afterwards"); + } + + @Test + @DisplayName("moves the last change time when a block is written") + void testTheChangeTimeMoves(Env env) { + final FalcoInstance instance = registered(env); + instance.loadChunk(0, 0).join(); + final long before = instance.getLastBlockChangeTime(); + + instance.setBlock(7, Y, 7, Block.STONE); + + assertNotEquals(before, instance.getLastBlockChangeTime(), + "a block write has to move the timestamp the batches read"); + } + + @Test + @DisplayName("loads the chunk a write lands in when auto chunk load is on") + void testAWriteLoadsItsChunk(Env env) { + final FalcoInstance instance = registered(env); + + instance.setBlock(600, Y, 600, Block.STONE); + + final Chunk chunk = instance.getChunkAt(600, 600); + assertTrue(chunk != null && chunk.isLoaded(), "the write has to have brought its chunk into the world"); + assertEquals(Block.STONE, instance.getBlock(600, Y, 600)); + } +} diff --git a/falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoInstanceGeneratorTest.java b/falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoInstanceGeneratorTest.java index 08c049a..9b405e3 100644 --- a/falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoInstanceGeneratorTest.java +++ b/falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoInstanceGeneratorTest.java @@ -21,6 +21,7 @@ import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertInstanceOf; +import static org.junit.jupiter.api.Assertions.assertNotEquals; import static org.junit.jupiter.api.Assertions.assertNotNull; import static org.junit.jupiter.api.Assertions.assertNull; import static org.junit.jupiter.api.Assertions.assertSame; @@ -42,7 +43,7 @@ *

* * @author TheMeinerLP - * @version 1.0.0 + * @version 1.2.0 * @since 0.3.0 */ @ExtendWith(MicrotusExtension.class) @@ -217,6 +218,87 @@ void testAForkIntoALoadedChunkReachesItImmediately(Env env) { assertEquals(Block.GOLD_BLOCK, instance.getBlock(16, MARKER_Y, 0)); } + /** + * Pins the order of the two halves of a commit, through the one thing that can observe it. + *

+ * A block which needs its own entry is written through {@code Chunk#setBlock}, and that method + * runs {@code if (needsCompleteHeightmapRefresh) calculateFullHeightmap()} before it refreshes + * anything. On a chunk that was just generated the flag is true, so the first such block latches + * both heightmaps — and {@code Heightmap#refresh(int)} sets a private {@code needsRefresh} to + * false which nothing public can set back, so whatever the chunk knew at that moment is what it + * keeps. If the specials of a section are written inside the loop that commits the palettes, that + * moment is halfway through the commit and the heights are computed over a chunk that is missing + * everything above the section the block happens to sit in. + *

+ *

+ * The case is built to make that gap wide and the wrong answer a specific number rather than a + * smell. Stone fills {@code y = -64..127}, which is the sections of index {@code 0..11}, and the + * block carrying nbt sits at {@code y = 64}, which is index {@code 8}. Committed in one pass the + * surface is {@code 127}; committed with the special written from inside the loop it is + * {@code 79} — the top of the highest section that had been committed when the latch fired — and + * {@code 79} is what this case reported in both heightmaps before the fix. + *

+ *

+ * The height is read rather than the packet, because {@code Heightmap#getHeight} answers from its + * array without recomputing anything once {@code needsRefresh} is false, which it is in both + * arms. The assertion therefore reads what the chunk stored and never triggers the refresh it is + * asserting about. + *

+ * + * @param env the environment which provides the server process + */ + @Test + void testTheHeightmapsSeeTheWholeChunkAndNotHalfOfIt(Env env) { + final Block marked = Block.CHEST.withNbt(CompoundBinaryTag.builder().putString("falco", "kept").build()); + final FalcoInstance instance = registered(env, null); + instance.setGenerator(unit -> { + unit.modifier().fill(new Vec(0, -64, 0), new Vec(16, 128, 16), Block.STONE); + unit.modifier().setBlock(0, 64, 0, marked); + }); + + instance.loadChunk(0, 0).join(); + + final Chunk chunk = instance.getChunk(0, 0); + + assertNotNull(chunk); + assertEquals(127, chunk.worldSurfaceHeightmap().getHeight(1, 1), + "the stone reaches y=127, and a heightmap latched halfway through the commit reports " + + "the top of the section the special block sits in instead"); + assertEquals(127, chunk.motionBlockingHeightmap().getHeight(1, 1), + "both heightmaps are latched by the same call, so both are wrong together"); + } + + /** + * Pins that both ways into the generator refresh the block change timestamp. + *

+ * The refresh used to sit at the end of the commit itself, where one line covered both entry + * points. It now sits at the two call sites, because the timestamp belongs to the instance and + * the commit belongs to {@link ChunkGeneration}. Nothing observed that line before, so a move + * which dropped it at one of the two would have been green everywhere. + *

+ * + * @param env the environment which provides the server process + */ + @Test + void testBothWaysIntoTheGeneratorMoveTheBlockChangeTime(Env env) { + final FalcoInstance instance = registered(env, null); + instance.setGenerator(writing(3, 5, Block.STONE)); + final long beforeLoad = instance.getLastBlockChangeTime(); + + instance.loadChunk(0, 0).join(); + + assertNotEquals(beforeLoad, instance.getLastBlockChangeTime(), + "a chunk which came out of the generator on its load carries blocks that were not there"); + + final long beforeGenerate = instance.getLastBlockChangeTime(); + + // The chunk is already loaded, so this is the second entry point and not the first one again. + instance.generateChunk(0, 0, writing(6, 7, Block.DIAMOND_BLOCK)).join(); + + assertNotEquals(beforeGenerate, instance.getLastBlockChangeTime(), + "a generator run over a chunk which is already loaded changes blocks just the same"); + } + @Test void testAChunkStaysEmptyWithoutAGenerator(Env env) { final FalcoInstance instance = registered(env, null); diff --git a/falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoInstancePersistenceTest.java b/falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoInstancePersistenceTest.java new file mode 100644 index 0000000..309e7bc --- /dev/null +++ b/falco-instance/src/test/java/net/onelitefeather/falco/instance/FalcoInstancePersistenceTest.java @@ -0,0 +1,371 @@ +package net.onelitefeather.falco.instance; + +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.ChunkLoader; +import net.minestom.server.instance.Instance; +import net.minestom.server.utils.chunk.ChunkSupplier; +import net.minestom.server.world.DimensionType; +import net.minestom.testing.Env; +import net.minestom.testing.extension.MicrotusExtension; +import org.jetbrains.annotations.Nullable; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; + +import java.util.Collection; +import java.util.List; +import java.util.UUID; +import java.util.concurrent.CompletionException; +import java.util.concurrent.atomic.AtomicBoolean; +import java.util.concurrent.atomic.AtomicInteger; +import java.util.concurrent.atomic.AtomicReference; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNotNull; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Pins everything a {@link FalcoInstance} does with a {@link ChunkLoader}, on both sides of the move + * of that code into {@link ChunkPersistence}. + *

+ * None of the four save entry points had a test when this class was written, and the branch that + * matters most had never been executed at all: a loader which saves in parallel takes a different + * path than one which does not, and a failure on either path has to reach the future the caller + * holds rather than the exception manager of the server. + *

+ *

+ * The three cases which do not save exist for the same reason one step later. Reading the instance + * once at construction and telling the loader that a chunk left were delegations no test in this + * module observed, so the two call sites of the one and the single call site of the other could have + * vanished in the move without anything turning red. They are pinned here first and moved second. + *

+ * + *

+ * One case is not about a save at all. {@code loadInstance} is the only caller which reaches a + * {@link FalcoInstance} before its constructor has finished, so it is the case which decides whether + * the fields the instance delegates to are assigned before or after that hook. + *

+ * + * @author TheMeinerLP + * @version 1.2.0 + * @since 0.4.0 + */ +@ExtendWith(MicrotusExtension.class) +@DisplayName("What a Falco instance does with its chunk loader") +class FalcoInstancePersistenceTest { + + /** + * A loader which counts what it was asked to save and can be told to throw. + */ + private static final class CountingLoader implements ChunkLoader { + + /** + * Whether this loader claims to support saving off the calling thread. + */ + private final boolean parallel; + + /** + * What every save call throws, null for a loader which succeeds. + */ + private final @Nullable RuntimeException failure; + + /** + * How often an instance save reached this loader. + */ + private final AtomicInteger instanceSaves = new AtomicInteger(); + + /** + * How often a chunk save reached this loader. + */ + private final AtomicInteger chunkSaves = new AtomicInteger(); + + /** + * How often a chunk was reported as having left the instance. + */ + private final AtomicInteger unloads = new AtomicInteger(); + + /** + * How often this loader was asked to read the data of an instance. + */ + private final AtomicInteger instanceLoads = new AtomicInteger(); + + /** + * The thread the last save ran on. + */ + private final AtomicReference lastThread = new AtomicReference<>(); + + /** + * Creates a loader. + * + * @param parallel whether it claims parallel saving + * @param failure what every save throws, null for none + */ + private CountingLoader(boolean parallel, @Nullable RuntimeException failure) { + this.parallel = parallel; + this.failure = failure; + } + + /** + * Knows no chunk at all, so every position is created by the instance instead. + * + * @param instance the instance which asks + * @param chunkX the chunk X + * @param chunkZ the chunk Z + * @return null, always + */ + @Override + public @Nullable Chunk loadChunk(Instance instance, int chunkX, int chunkZ) { + return null; + } + + @Override + public boolean supportsParallelSaving() { + return this.parallel; + } + + @Override + public void saveInstance(Instance instance) { + this.lastThread.set(Thread.currentThread()); + this.instanceSaves.incrementAndGet(); + if (this.failure != null) throw this.failure; + } + + @Override + public void saveChunk(Chunk chunk) { + this.lastThread.set(Thread.currentThread()); + this.chunkSaves.incrementAndGet(); + if (this.failure != null) throw this.failure; + } + + @Override + public void saveChunks(Collection chunks) { + this.lastThread.set(Thread.currentThread()); + this.chunkSaves.addAndGet(chunks.size()); + if (this.failure != null) throw this.failure; + } + + @Override + public void unloadChunk(Chunk chunk) { + this.unloads.incrementAndGet(); + } + + @Override + public void loadInstance(Instance instance) { + this.instanceLoads.incrementAndGet(); + } + } + + /** + * A loader which configures the instance it is handed while that instance is still being built. + *

+ * {@code ChunkLoader#loadInstance} is a documented Minestom hook and it runs from the constructor + * of the instance, so it is the one caller which can reach a {@link FalcoInstance} whose + * constructor has not finished. Everything the instance delegates has to stand by then; a field + * assigned after this call is read as null here and the constructor dies with a + * {@link NullPointerException} that names it. + *

+ */ + private static final class ConfiguringLoader implements ChunkLoader { + + /** + * The supplier this loader installs while the instance is being built. + */ + private final ChunkSupplier supplier = FalcoChunk::new; + + /** + * What the instance reported as its supplier before this loader changed it. + */ + private final AtomicReference supplierBefore = new AtomicReference<>(); + + /** + * What the instance reported about auto loading before this loader changed it. + */ + private final AtomicBoolean autoLoadBefore = new AtomicBoolean(); + + @Override + public @Nullable Chunk loadChunk(Instance instance, int chunkX, int chunkZ) { + return null; + } + + @Override + public void saveChunk(Chunk chunk) { + // This loader is about the read at construction, not about saving. + } + + @Override + public void loadInstance(Instance instance) { + final FalcoInstance falco = (FalcoInstance) instance; + this.supplierBefore.set(falco.getChunkSupplier()); + this.autoLoadBefore.set(falco.hasEnabledAutoChunkLoad()); + falco.setChunkSupplier(this.supplier); + falco.enableAutoChunkLoad(false); + } + } + + /** + * Creates a registered instance with the given loader. + * + * @param env the environment which provides the server process + * @param loader the loader of the instance + * @return the registered instance + */ + private static FalcoInstance registered(Env env, ChunkLoader loader) { + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD, loader); + env.process().instance().registerInstance(instance); + return instance; + } + + @Test + @DisplayName("saves the instance on the calling thread when the loader is not parallel") + void testSaveInstanceOnTheCallingThread(Env env) { + final CountingLoader loader = new CountingLoader(false, null); + final FalcoInstance instance = registered(env, loader); + + instance.saveInstance().join(); + + assertEquals(1, loader.instanceSaves.get()); + assertSame(Thread.currentThread(), loader.lastThread.get(), + "a loader without parallel support must not be moved off the calling thread"); + } + + @Test + @DisplayName("saves the instance off the calling thread when the loader is parallel") + void testSaveInstanceOnAVirtualThread(Env env) { + final CountingLoader loader = new CountingLoader(true, null); + final FalcoInstance instance = registered(env, loader); + + instance.saveInstance().join(); + + assertEquals(1, loader.instanceSaves.get()); + assertTrue(loader.lastThread.get().isVirtual(), + "a loader with parallel support has to be run on a virtual thread"); + } + + @Test + @DisplayName("hands a failing save back to the caller instead of swallowing it") + void testAFailingSaveReachesTheCaller(Env env) { + final RuntimeException boom = new IllegalStateException("the disk is on fire"); + final FalcoInstance instance = registered(env, new CountingLoader(false, boom)); + + final CompletionException thrown = assertThrows(CompletionException.class, + () -> instance.saveInstance().join()); + + assertSame(boom, thrown.getCause(), "the failure of the loader is the failure of the future"); + } + + @Test + @DisplayName("hands a failing parallel save back to the caller as well") + void testAFailingParallelSaveReachesTheCaller(Env env) { + final RuntimeException boom = new IllegalStateException("the disk is still on fire"); + final FalcoInstance instance = registered(env, new CountingLoader(true, boom)); + + final CompletionException thrown = assertThrows(CompletionException.class, + () -> instance.saveInstance().join()); + + assertSame(boom, thrown.getCause(), "moving the work to a virtual thread must not lose the failure"); + } + + @Test + @DisplayName("saves one chunk and every chunk through the loader") + void testChunkSaves(Env env) { + final CountingLoader loader = new CountingLoader(false, null); + final FalcoInstance instance = registered(env, loader); + final Chunk chunk = instance.loadChunk(0, 0).join(); + instance.loadChunk(1, 0).join(); + + instance.saveChunkToStorage(chunk).join(); + assertEquals(1, loader.chunkSaves.get()); + + instance.saveChunksToStorage().join(); + assertEquals(3, loader.chunkSaves.get(), "the second call has to hand over both loaded chunks"); + } + + @Test + @DisplayName("keeps the chunks it already has when the loader is swapped") + void testSwappingTheLoader(Env env) { + final CountingLoader first = new CountingLoader(false, null); + final CountingLoader second = new CountingLoader(false, null); + final FalcoInstance instance = registered(env, first); + final Chunk chunk = instance.loadChunk(0, 0).join(); + + instance.setChunkLoader(second); + + assertSame(second, instance.getChunkLoader()); + assertSame(chunk, instance.getChunk(0, 0), "swapping the loader must not touch loaded chunks"); + instance.saveChunkToStorage(chunk).join(); + assertEquals(0, first.chunkSaves.get(), "the old loader must not see the save"); + assertEquals(1, second.chunkSaves.get(), "the new loader has to"); + } + + @Test + @DisplayName("reads the instance through its loader while it is built, and never again") + void testTheInstanceIsReadOnceWhenItIsBuilt(Env env) { + final CountingLoader first = new CountingLoader(false, null); + final CountingLoader second = new CountingLoader(false, null); + final FalcoInstance instance = registered(env, first); + + instance.setChunkLoader(second); + + assertEquals(1, first.instanceLoads.get(), "building an instance has to read its data once"); + assertEquals(0, second.instanceLoads.get(), + "a loader swapped in later must not overwrite live state with what is on disk"); + } + + @Test + @DisplayName("tells the loader that a chunk left the instance") + void testAnUnloadReachesTheLoader(Env env) { + final CountingLoader loader = new CountingLoader(false, null); + final FalcoInstance instance = registered(env, loader); + final Chunk chunk = instance.loadChunk(0, 0).join(); + + instance.unloadChunk(chunk); + + assertEquals(1, loader.unloads.get(), + "the loader may hold bookkeeping for the chunk and has to hear that it left"); + } + + @Test + @DisplayName("is already usable when its loader reads it from the constructor") + void testTheInstanceIsUsableWhileTheLoaderReadsIt(Env env) { + final ConfiguringLoader loader = new ConfiguringLoader(); + + final FalcoInstance instance = registered(env, loader); + + assertNotNull(loader.supplierBefore.get(), + "the chunk supplier has to stand before the loader is let into the instance"); + assertTrue(loader.autoLoadBefore.get(), + "auto chunk load has to report its default rather than throw while the loader reads"); + assertSame(loader.supplier, instance.getChunkSupplier(), + "what the loader configured during the read has to survive the rest of the constructor"); + assertFalse(instance.hasEnabledAutoChunkLoad(), + "a loader which switches auto loading off during the read has to be obeyed"); + } + + @Test + @DisplayName("is usable on its own, without an instance driving it") + void testThePartRunsWithoutTheFacade(Env env) { + final CountingLoader loader = new CountingLoader(false, null); + final FalcoInstance instance = registered(env, loader); + final ChunkPersistence persistence = new ChunkPersistence(loader); + + persistence.saveInstance(instance).join(); + persistence.saveChunks(List.of()).join(); + + assertEquals(1, loader.instanceSaves.get()); + assertSame(loader, persistence.loader()); + } + + @Test + @DisplayName("uses a loader which saves and loads nothing when it is given none") + void testTheDefaultLoaderIsTheNoopOne(Env env) { + registered(env, ChunkLoader.noop()); + final ChunkPersistence persistence = new ChunkPersistence(null); + + assertNotNull(persistence.loader(), "a null loader has to become the noop loader, not stay null"); + assertNull(persistence.read(null, 0, 0), "the noop loader reads nothing"); + } +} diff --git a/falco-instance/src/test/java/net/onelitefeather/falco/instance/InstanceFacadeTest.java b/falco-instance/src/test/java/net/onelitefeather/falco/instance/InstanceFacadeTest.java new file mode 100644 index 0000000..b5dbe4e --- /dev/null +++ b/falco-instance/src/test/java/net/onelitefeather/falco/instance/InstanceFacadeTest.java @@ -0,0 +1,108 @@ +package net.onelitefeather.falco.instance; + +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +import java.lang.reflect.Field; +import java.lang.reflect.Modifier; +import java.util.List; +import java.util.Set; +import java.util.stream.Collectors; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Asserts that {@link FalcoInstance} is a facade and not the class it replaced with delegation in + * front of it. + *

+ * §4.3 of the design says it in one sentence: the facade must hold no state of its own, or it is + * the same class with delegation in front of it. §8 lists whether that holds as the open question + * of this stage. A question that can only be answered by a person reading the file is answered again + * every time somebody reads it, and differently; this class answers it once per build. + *

+ * + *

What is asserted, which is less than that sentence

+ *

+ * The two cases below assert one thing: {@link FalcoInstance} declares exactly four non-static, + * non-synthetic fields, every one of them {@code final} and of one of the four part types, each type + * once. That is a property of the declaration and nothing more. It does not assert that no value the + * facade acts on lives anywhere — {@link ChunkPersistence#saveOnShutdown()} and + * {@link ChunkPersistence#ownsLoader()} are read by {@code FalcoInstance#shutdown} and by no method + * of the class that holds them, so a fifth field could in principle be avoided by parking its value + * in a part that never asks about it, and these cases would stay green. + *

+ *

+ * The gap is written here rather than papered over, because the difference between what a check does + * and what its name suggests is the failure this repository has been bitten by repeatedly. What is + * bought is still the thing §8 asked for and the thing a later change actually threatens: nobody can + * hang a map, a counter or a flag back onto the facade without a red build. + *

+ * + *

Why this is reflection, and why that is allowed here

+ *

+ * NFR-001 forbids reflection in the modules, so that they run without {@code --add-opens} and without + * an open module. It says nothing about a test, and this repository already reads private fields of a + * foreign library in {@code JolMeasurement} for a reason of the same shape: the property being + * checked is a property of the declaration, and nothing but the declaration can be asked about it. + * The alternative — a JOL walk of the shallow size — was rejected because it cannot tell a fifth + * reference field from padding, which is exactly the blind spot the stage 2 result had to write down + * about {@code ChunkFootprintTest}. + *

+ * + * @author TheMeinerLP + * @version 1.0.1 + * @since 0.4.0 + */ +@DisplayName("The instance facade") +class InstanceFacadeTest { + + /** + * The four types a field of the facade is allowed to have. + */ + private static final Set> PARTS = Set.of( + ChunkRegistry.class, ChunkLifecycle.class, BlockWriter.class, ChunkPersistence.class); + + /** + * Returns every instance field the facade declares itself, ignoring what it inherits. + * + * @return the declared, non-static fields of the facade + */ + private static List declaredFields() { + return java.util.Arrays.stream(FalcoInstance.class.getDeclaredFields()) + .filter(field -> !Modifier.isStatic(field.getModifiers())) + .filter(field -> !field.isSynthetic()) + .toList(); + } + + @Test + @DisplayName("declares exactly the four parts it delegates to") + void testTheFacadeDeclaresOnlyItsParts() { + final List fields = declaredFields(); + final String names = fields.stream() + .map(field -> field.getType().getSimpleName() + " " + field.getName()) + .collect(Collectors.joining(", ")); + + assertEquals(PARTS.size(), fields.size(), + "the facade may hold one reference per part and nothing else, but it declares: " + names); + for (Field field : fields) { + assertTrue(PARTS.contains(field.getType()), + "the facade declares a field of type " + field.getType().getName() + " named " + + field.getName() + ", which is state of its own rather than a part; either it " + + "belongs in one of " + PARTS + " or the split of stage 3 has been undone"); + } + assertEquals(PARTS, + fields.stream().map(Field::getType).collect(Collectors.toUnmodifiableSet()), + "every part has to be reachable from the facade, and each exactly once"); + } + + @Test + @DisplayName("declares every one of them final") + void testTheFacadeCannotSwapItsParts() { + for (Field field : declaredFields()) { + assertTrue(Modifier.isFinal(field.getModifiers()), + "the field " + field.getName() + " is not final; a part that can be replaced at " + + "runtime is a part two threads can disagree about"); + } + } +} diff --git a/falco-instance/src/test/java/net/onelitefeather/falco/instance/LazySectionBlockStorageTest.java b/falco-instance/src/test/java/net/onelitefeather/falco/instance/LazySectionBlockStorageTest.java new file mode 100644 index 0000000..4306d55 --- /dev/null +++ b/falco-instance/src/test/java/net/onelitefeather/falco/instance/LazySectionBlockStorageTest.java @@ -0,0 +1,338 @@ +package net.onelitefeather.falco.instance; + +import net.minestom.server.MinecraftServer; +import net.minestom.server.instance.Section; +import net.minestom.server.instance.block.Block; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +import java.util.concurrent.BrokenBarrierException; +import java.util.concurrent.CyclicBarrier; +import java.util.concurrent.atomic.AtomicReference; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNotSame; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Pins down what {@link LazySectionBlockStorage} does beyond the contract of {@link BlockStorage}, + * which is the whole of stage 2: that a section which holds nothing costs nothing. + *

+ * The contract itself is not repeated here. {@code BlockStorageTest} runs every one of its cases + * against both layouts, so a case that only says "what went in comes out" belongs there and would be + * a duplicate here. What is left is exactly the set of statements that are false for the eager + * storage: how many sections the storage owns, which slot points at the shared section, and which + * call moves a slot from one state to the other. + *

+ * + *

Why every case counts sections instead of reading blocks

+ *

+ * A lazy storage that materialised every section on the first touch would satisfy every read and + * write assertion in this file and save nothing at all, which is the failure mode this stage exists + * to prevent. {@link BlockStorage#materialisedSections()} and {@link BlockStorage#shared(int)} are + * the only two observations that can tell the two apart, so they carry the assertions and the block + * reads are there to prove that the saving did not cost correctness. + *

+ * + * @author TheMeinerLP + * @version 1.2.0 + * @since 0.4.0 + */ +@DisplayName("The lazy block storage of a chunk") +class LazySectionBlockStorageTest { + + private static final int SECTIONS = 24; + private static final int MIN_SECTION = -4; + + @BeforeAll + static void server() { + if (MinecraftServer.process() == null) { + MinecraftServer.init(); + } + } + + private static LazySectionBlockStorage storage() { + return new LazySectionBlockStorage(MIN_SECTION, SECTIONS); + } + + @Test + @DisplayName("owns no section at all before anything is written") + void testNothingIsMaterialisedUpFront() { + final LazySectionBlockStorage storage = storage(); + + assertEquals(0, storage.materialisedSections()); + for (int section = 0; section < SECTIONS; section++) { + assertTrue(storage.shared(section), "section " + section + " has to start out shared"); + } + } + + @Test + @DisplayName("shares one and the same section between every empty slot and every chunk") + void testEverySharedSlotIsTheSameObject() { + final LazySectionBlockStorage first = storage(); + final LazySectionBlockStorage second = storage(); + final Section shared = first.view(0); + + for (int section = 0; section < SECTIONS; section++) { + assertSame(shared, first.view(section)); + assertSame(shared, second.view(section)); + } + } + + @Test + @DisplayName("materialises exactly the section that was written to and leaves the others shared") + void testAWriteMaterialisesOneSection() { + final LazySectionBlockStorage storage = storage(); + + storage.setBlock(1, 20, 3, Block.STONE); + + assertEquals(1, storage.materialisedSections()); + assertFalse(storage.shared(5), "y=20 belongs to section index 5 of a chunk starting at -64"); + for (int section = 0; section < SECTIONS; section++) { + if (section == 5) continue; + assertTrue(storage.shared(section), "section " + section + " was not written to"); + } + assertEquals(Block.STONE, storage.getBlock(1, 20, 3, Block.Getter.Condition.NONE)); + assertEquals(Block.AIR, storage.getBlock(1, 36, 3, Block.Getter.Condition.NONE)); + } + + @Test + @DisplayName("does not materialise a section that is written air, but does for cave air") + void testWritingAirLeavesTheSlotShared() { + final LazySectionBlockStorage storage = storage(); + + storage.setBlock(1, 20, 3, Block.AIR); + + assertEquals(0, storage.materialisedSections(), + "writing the state the shared section already holds everywhere changes nothing, and " + + "a loader that walks a whole chunk writing air would otherwise materialise " + + "every section it touched"); + + storage.setBlock(1, 20, 3, Block.CAVE_AIR); + + assertEquals(1, storage.materialisedSections(), + "cave air is a different state id from air and has to be stored"); + assertEquals(Block.CAVE_AIR, storage.getBlock(1, 20, 3, Block.Getter.Condition.NONE)); + } + + /** + * A read of a shared slot answers air, materialises nothing, and does not reach a palette. + *

+ * The first two are asserted by counting; the third needs an observation, because a palette read + * of the shared section has no side effect and answers air as well. {@code Palette#get} validates + * its coordinates before it takes its own {@code bitsPerEntry == 0} shortcut + * ({@code PaletteImpl#get} calls {@code validateCoord} on its first line), so a coordinate the + * palette rejects is exactly the input that separates a read which reached one from a read which + * did not: the eager layout throws for {@code x = 16}, the lazy one answers air. Without the + * shortcut in {@link LazySectionBlockStorage#getBlock(int, int, int, Block.Getter.Condition)} + * this case throws instead of passing, which is the whole reason the pair of assertions is here — + * every other read in this file is green with the shortcut and without it. + *

+ *

+ * The divergence is asserted, not endorsed. {@link BlockStorage} requires the caller to have + * folded the coordinate into the chunk already, so {@code x = 16} is a caller bug under both + * layouts and neither answer is more correct than the other; what is pinned is that the lazy + * layout does not pay a palette call to find that out. A later change that decides the two + * layouts must reject it alike belongs in the contract test and has to fail here first. + *

+ */ + @Test + @DisplayName("answers a read of a shared section without touching a palette") + void testReadingASharedSectionDoesNotMaterialise() { + final LazySectionBlockStorage storage = storage(); + + for (int y = -64; y < 320; y += 16) { + assertEquals(Block.AIR, storage.getBlock(0, y, 0, Block.Getter.Condition.NONE)); + } + assertEquals(0, storage.materialisedSections()); + + assertThrows(IllegalArgumentException.class, + () -> new SectionBlockStorage(MIN_SECTION, SECTIONS) + .getBlock(16, 20, 0, Block.Getter.Condition.NONE), + "a read that reaches a palette is refused an x of 16; if Minestom ever stopped " + + "refusing it, the assertion below would no longer prove anything"); + assertEquals(Block.AIR, storage.getBlock(16, 20, 0, Block.Getter.Condition.NONE), + "the shared slot answers without asking its palette, so the coordinate the palette " + + "would have refused never reaches one"); + assertEquals(0, storage.materialisedSections()); + } + + @Test + @DisplayName("materialises every section when the boundary hands them out") + void testTheBoundaryMaterialisesEverything() { + final LazySectionBlockStorage byOne = storage(); + final LazySectionBlockStorage byAll = storage(); + + byOne.section(5); + assertEquals(1, byOne.materialisedSections(), + "section(int) is the boundary for one section, not for the chunk"); + + byAll.sections(); + assertEquals(SECTIONS, byAll.materialisedSections(), + "sections() hands the whole chunk to a caller that may write to any of it"); + } + + /** + * A materialised section must be a fresh one and not a clone of the shared one. + *

+ * The property that separates the two is the light. A fresh {@code Section} has never had + * {@code SkyLight#set} called on it, so it does not claim to have light to send; a clone of the + * shared section has, because {@code Section#clone} runs {@code skyLight.set(skyLight.array())} + * unconditionally. The clone in this test is not decoration: it states the fact about Minestom + * the implementation rests on, so that a Minestom which stopped raising {@code needsSend} there + * would fail this case rather than silently turn the assertion below into one that holds for + * both branches. + *

+ *

+ * What is deliberately not asserted is {@code skyLight().array().length}. The brief for + * this task proposed it, but it does not separate the two: {@code SkyLight#set} stores + * {@code LightCompute.EMPTY_CONTENT}, and {@code SkyLight#array} bakes that back into + * {@code UNSET_CONTENT} and returns a zero length array for a clone exactly as it does for a + * fresh section. + *

+ */ + @Test + @DisplayName("materialises with a fresh section rather than a clone of the shared one") + void testMaterialisationDoesNotCloneTheFlyweight() { + final LazySectionBlockStorage storage = storage(); + final Section shared = storage.view(0); + + storage.setBlock(0, 0, 0, Block.STONE); + + assertSame(shared, storage.view(0), + "y=0 is section index 4, so section 0 must have been left alone"); + + final Section written = storage.view(4); + + assertNotSame(shared, written, "the write to y=0 has to have materialised section 4"); + assertTrue(shared.clone().skyLight().requiresSend(), + "the reason this class must not materialise through clone: Section#clone hands the " + + "unset light of the shared section to SkyLight#set, which raises needsSend"); + assertFalse(written.skyLight().requiresSend(), + "a section that has never been lit has nothing to send"); + } + + @Test + @DisplayName("copies without materialising what the original had not materialised") + void testCopyKeepsSharing() { + final LazySectionBlockStorage original = storage(); + original.setBlock(1, 20, 3, Block.STONE); + + final BlockStorage copy = original.copy(); + + assertEquals(1, copy.materialisedSections()); + assertEquals(Block.STONE, copy.getBlock(1, 20, 3, Block.Getter.Condition.NONE)); + + copy.setBlock(1, 20, 3, Block.DIRT); + assertEquals(Block.STONE, original.getBlock(1, 20, 3, Block.Getter.Condition.NONE), + "a copy that shared a materialised section would change the original"); + } + + /** + * Holds the one step of this class that no chunk lock covers. + *

+ * Every other case in this file runs on one thread, and on one thread a materialisation that + * reads a slot, allocates and stores is indistinguishable from one that publishes with a compare + * and exchange. The difference is only visible against a second thread, and that second thread is + * not hypothetical: {@code Instance#getBlockLight}, {@code Instance#getSkyLight} and + * {@code Instance#invalidateSection} all reach {@link BlockStorage#section(int)} through + * {@code Chunk#getSection} or {@code Chunk#getSectionAt} while holding no chunk lock at all, so a + * light query on any thread is exactly the reader modelled here. + *

+ *

+ * What the assertion catches is a lost write and not a torn one. The reader below writes nothing; + * it only asks for the section, which is the call that used to allocate one and store it over + * whatever the writer had just put there. The block the writer stored into the overwritten + * section is then unreachable, and — this is what makes it worth a case of its own — nothing + * fails: no exception, no log, and the read answers air through the shortcut for a shared slot. + *

+ *

+ * A stress case rather than a scheduled one, because the window it aims at is the handful of + * instructions between the read of a slot and the store into it, and nothing in this class can be + * paused inside it. The two threads are aligned at every round and both walk the same twenty-four + * slots in the same order, which is what makes a round a genuine collision attempt rather than a + * coin toss. With the compare and exchange replaced by the plain + * {@code this.sections[index] = created} it used to be, this case failed in all five runs of the + * mutation, in rounds {@code 3, 5, 0, 3} and {@code 3} — so the four thousand rounds are three + * orders of magnitude more than the defect needs, and they are what makes the case a statement + * rather than a coin toss. It says nothing about how likely the defect is in production, where + * the two threads are not aligned by a barrier. The whole case costs under two seconds. + *

+ * + * @throws InterruptedException if the test thread is interrupted while joining the two workers + */ + @Test + @DisplayName("does not lose a written block to a reader that materialises the same slot") + void testMaterialisationSurvivesAConcurrentReader() throws InterruptedException { + final int rounds = 4_000; + final CyclicBarrier start = new CyclicBarrier(2); + final AtomicReference failure = new AtomicReference<>(); + + for (int round = 0; round < rounds && failure.get() == null; round++) { + final LazySectionBlockStorage storage = storage(); + // The reader is the lock-free side: it only asks for sections, exactly as a light query + // does, and every section it hands back it may have allocated itself. + final Thread reader = new Thread(() -> { + await(start, failure); + for (int section = 0; section < SECTIONS; section++) { + storage.section(section); + } + }, "lazy-storage-reader"); + final Thread writer = new Thread(() -> { + await(start, failure); + for (int section = 0; section < SECTIONS; section++) { + storage.setBlock(0, (MIN_SECTION + section) * 16, 0, Block.STONE); + } + }, "lazy-storage-writer"); + + reader.start(); + writer.start(); + writer.join(); + reader.join(); + + for (int section = 0; section < SECTIONS; section++) { + assertEquals(Block.STONE, + storage.getBlock(0, (MIN_SECTION + section) * 16, 0, Block.Getter.Condition.NONE), + "round " + round + ": the block written into section " + section + + " was stored into a section the reader then replaced"); + } + } + assertNull(failure.get(), "neither worker may fail on anything but the assertion above"); + } + + /** + * Waits at the barrier and records what went wrong instead of throwing into a worker thread. + * + * @param barrier the barrier both workers meet at before every round + * @param failure where a failure of a worker is recorded for the test thread to see + */ + private static void await(CyclicBarrier barrier, AtomicReference failure) { + try { + barrier.await(); + } catch (InterruptedException | BrokenBarrierException throwable) { + failure.compareAndSet(null, throwable); + Thread.currentThread().interrupt(); + } + } + + @Test + @DisplayName("returns every slot to the shared section when it is cleared") + void testClearReleasesEverySection() { + final LazySectionBlockStorage storage = storage(); + storage.setBlock(1, 20, 3, Block.STONE); + final Section materialised = storage.view(5); + + storage.clear(); + + assertEquals(0, storage.materialisedSections()); + assertEquals(Block.AIR, storage.getBlock(1, 20, 3, Block.Getter.Condition.NONE)); + assertEquals(0, materialised.blockPalette().count(), + "a caller holding the section from before the reset has to see it emptied, which is " + + "what Section#clear does and what DynamicChunk#reset relies on"); + } +} diff --git a/falco-instance/src/test/java/net/onelitefeather/falco/instance/PaletteCompactionTest.java b/falco-instance/src/test/java/net/onelitefeather/falco/instance/PaletteCompactionTest.java new file mode 100644 index 0000000..a6ec63e --- /dev/null +++ b/falco-instance/src/test/java/net/onelitefeather/falco/instance/PaletteCompactionTest.java @@ -0,0 +1,196 @@ +package net.onelitefeather.falco.instance; + +import net.minestom.server.instance.palette.Palette; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * Holds {@link PaletteCompaction} to the one promise that matters: a palette it packs has to come out + * exactly as {@code Palette#optimize(Optimization.SIZE)} would have left it. + *

+ * The class is a performance guard, and a performance guard has a dangerous failure mode that no + * timing can see. Skipping work that would have achieved nothing is invisible in the result; skipping + * work that would have narrowed a palette is also invisible in the result, unless something compares + * the two. That comparison is what every case here does: the same content is packed once through the + * guard and once through the unconditional call, and both the width and the content have to agree. + * A threshold that is off by one, a probe that samples the wrong positions or a rule that forgets the + * {@code fill} branch of {@code optimize} all show up as a disagreement rather than as a slow server. + *

+ * + *

Why the fixtures are written through setAll

+ *

+ * {@code PaletteImpl#setAll} is the method a generated section comes out of, and it decides the width + * of the palette without looking at the content: a supplier that answered one constant value goes to + * {@code fill}, and every other supplier goes to {@code makeDirect}, so a section holding two states + * and a section holding a thousand are both fifteen bits wide. That is the input the commit is handed + * and therefore the input the guard has to be right about. The two cases that build their fixture + * through {@code Palette#set} cover the other shape, an indirect palette grown one write at a time, + * which is what a chunk loader and every block write leave behind. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@DisplayName("What the palette compaction may skip") +class PaletteCompactionTest { + + /** + * Builds a block palette the way {@code UnitModifier#setAllRelative} leaves one. + * + * @param distinctStates how many distinct values the palette ends up holding + * @return the palette + */ + private static Palette generated(int distinctStates) { + final Palette palette = Palette.blocks(); + + palette.setAll((x, y, z) -> 1 + (x + (y << 4) + (z << 8)) % distinctStates); + return palette; + } + + /** + * Demands that two palettes hold the same value at every position. + *

+ * The walk is written out rather than left to {@code Palette#compare}, which cannot answer this + * question here. {@code PaletteImpl#compare} opens on {@code palette.count != this.count}, and the + * {@code count} field carries the stored value in the single value mode and the number of non-air + * entries in every other mode, so a palette that was just collapsed by {@code fill} is reported as + * different from the indirect palette it was collapsed from. Comparing a packed palette against + * its source is exactly the case that runs into it. + *

+ * + * @param expected the palette the content is taken from + * @param actual the palette the content is compared against + * @param message what a difference would mean + */ + private static void assertSameContent(Palette expected, Palette actual, String message) { + final int dimension = expected.dimension(); + + for (int x = 0; x < dimension; x++) { + for (int y = 0; y < dimension; y++) { + for (int z = 0; z < dimension; z++) { + assertEquals(expected.get(x, y, z), actual.get(x, y, z), + message + " at " + x + ", " + y + ", " + z); + } + } + } + } + + /** + * Packs a palette twice, once through the guard and once unconditionally, and demands the same + * outcome from both. + * + * @param fixture the palette to pack, which is cloned and left alone + * @return the width both routes ended at + */ + private static int packedWidthOf(Palette fixture) { + final Palette guarded = fixture.clone(); + final Palette unconditional = fixture.clone(); + + PaletteCompaction.packBlocks(guarded); + unconditional.optimize(Palette.Optimization.SIZE); + + assertEquals(unconditional.bitsPerEntry(), guarded.bitsPerEntry(), + "the guard skipped an optimisation that would have changed the width, which is the one " + + "way it can be wrong that no benchmark would notice"); + assertSameContent(fixture, guarded, "packing changed the content of the palette"); + assertSameContent(unconditional, guarded, "the two routes disagree about the content"); + return guarded.bitsPerEntry(); + } + + @ParameterizedTest + @ValueSource(ints = {1, 2, 3, 16, 17, 200, 255, 256, 257, 300, 1024, 4096}) + @DisplayName("a generated palette is packed exactly as the unconditional call would pack it") + void testTheGuardedPackMatchesTheUnconditionalOne(int distinctStates) { + packedWidthOf(generated(distinctStates)); + } + + @Test + @DisplayName("the widths the two sides of the threshold end at are the ones the palette source promises") + void testTheWidthsAroundTheThreshold() { + assertEquals(0, packedWidthOf(generated(1)), + "one state never reaches makeDirect: Palette#setAll sends a constant supplier to fill"); + assertEquals(Palette.BLOCK_PALETTE_MIN_BITS, packedWidthOf(generated(2)), + "two states fit in the minimum width of four bits"); + assertEquals(Palette.BLOCK_PALETTE_MAX_BITS, packedWidthOf(generated(256)), + "256 states are exactly what an indirect block palette can index, and this is the case " + + "a threshold that is off by one gets wrong"); + assertEquals(Palette.BLOCK_PALETTE_DIRECT_BITS, packedWidthOf(generated(257)), + "one state more than the indirect mode can index, so the palette has to stay direct - " + + "and this is the case the guard exists to stop paying for"); + } + + @Test + @DisplayName("the guard refuses a palette that is provably past the indirect ceiling") + void testTheGuardSkipsWhatCannotBeNarrowed() { + assertFalse(PaletteCompaction.canNarrow(generated(1024), + Palette.BLOCK_PALETTE_MIN_BITS, Palette.BLOCK_PALETTE_MAX_BITS), + "1024 distinct states in 4096 entries: the probe reaches 257 of them long before its " + + "sample is exhausted, and downsizeWithPalette could not have stored them"); + assertTrue(PaletteCompaction.canNarrow(generated(256), + Palette.BLOCK_PALETTE_MIN_BITS, Palette.BLOCK_PALETTE_MAX_BITS), + "256 distinct states still fit, so this one has to be attempted"); + } + + @Test + @DisplayName("the guard refuses a palette that is already in the single value mode") + void testTheGuardSkipsASingleValuePalette() { + final Palette palette = Palette.blocks(); + + palette.fill(1); + + assertFalse(PaletteCompaction.canNarrow(palette, + Palette.BLOCK_PALETTE_MIN_BITS, Palette.BLOCK_PALETTE_MAX_BITS), + "optimize returns on its opening bitsPerEntry == 0, so there is nothing to attempt"); + } + + @Test + @DisplayName("a palette grown by single writes is packed as the unconditional call packs it") + void testAPaletteGrownByWritesIsPackedTheSameWay() { + final Palette twoStates = Palette.blocks(); + final Palette oneState = Palette.blocks(); + + for (int x = 0; x < 16; x++) { + for (int y = 0; y < 16; y++) { + for (int z = 0; z < 16; z++) { + twoStates.set(x, y, z, (x + y + z) % 2 == 0 ? 1 : 2); + oneState.set(x, y, z, 1); + } + } + } + + assertEquals(Palette.BLOCK_PALETTE_MIN_BITS, twoStates.bitsPerEntry(), + "Palette#set grows the palette to what it needs, which for two states is the minimum " + + "width; there is nothing left for optimize to take"); + assertEquals(Palette.BLOCK_PALETTE_MIN_BITS, packedWidthOf(twoStates)); + assertEquals(0, packedWidthOf(oneState), + "one distinct value collapses to the single value mode even at the minimum width, " + + "through the fill branch of optimize rather than through a downsize. A guard " + + "which refused every palette that is already at the minimum width would " + + "leave this palette holding 2048 bytes for one value"); + } + + @Test + @DisplayName("a biome palette is packed as the unconditional call packs it") + void testABiomePaletteIsPackedTheSameWay() { + final Palette guarded = Palette.biomes(); + final Palette unconditional = Palette.biomes(); + + guarded.setAll((x, y, z) -> (x + y + z) % 2 == 0 ? 1 : 2); + unconditional.setAll((x, y, z) -> (x + y + z) % 2 == 0 ? 1 : 2); + + PaletteCompaction.packBiomes(guarded); + unconditional.optimize(Palette.Optimization.SIZE); + + assertEquals(unconditional.bitsPerEntry(), guarded.bitsPerEntry()); + assertSameContent(unconditional, guarded, "the two routes disagree about the content"); + assertEquals(Palette.BIOME_PALETTE_MIN_BITS, guarded.bitsPerEntry(), + "two biomes need one bit, the minimum width of a biome palette"); + } +} diff --git a/falco-instance/src/test/java/net/onelitefeather/falco/instance/SectionMaterialisationTest.java b/falco-instance/src/test/java/net/onelitefeather/falco/instance/SectionMaterialisationTest.java new file mode 100644 index 0000000..eab6bbf --- /dev/null +++ b/falco-instance/src/test/java/net/onelitefeather/falco/instance/SectionMaterialisationTest.java @@ -0,0 +1,493 @@ +package net.onelitefeather.falco.instance; + +import net.kyori.adventure.key.Key; +import net.minestom.server.MinecraftServer; +import net.minestom.server.instance.Chunk; +import net.minestom.server.instance.InstanceContainer; +import net.minestom.server.instance.block.Block; +import net.minestom.server.instance.block.BlockHandler; +import net.minestom.server.instance.generator.Generator; +import net.minestom.server.instance.palette.Palette; +import net.minestom.server.network.ConnectionState; +import net.minestom.server.network.packet.server.SendablePacket; +import net.minestom.server.registry.RegistryKey; +import net.minestom.server.world.DimensionType; +import net.minestom.server.world.biome.Biome; +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +import java.util.UUID; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNotEquals; +import static org.junit.jupiter.api.Assertions.assertNotNull; + +/** + * Counts what a caller makes a {@link FalcoChunk} allocate at the three boundaries where Minestom + * insists on real {@code Section} objects. + *

+ * The saving of {@link LazySectionBlockStorage} is only worth what survives contact with those + * boundaries. A chunk which holds nothing until something is written into it, and then materialises + * all twenty-four sections the first time anybody sends it, has saved nothing; the spec records + * exactly that as an open risk. Every case below therefore states a number rather than a direction, + * and the number is read off {@link BlockStorage#materialisedSections()}, which is the one counter + * that cannot be satisfied by an intention. + *

+ * + *

Why the measurement never goes through the chunk

+ *

+ * {@code Chunk#getSections()} and {@code Chunk#getSection(int)} are not reads on a lazy chunk, they + * are writes: both materialise, which is what the two cases named after them assert. A test which + * counted sections by walking either of them would build the very sections it claims to have found, + * and the previous footprint measurement of this project was wrong for precisely that reason. The + * counter is asked directly instead, through {@link FalcoChunk#storage()}, and no case here touches + * a section except the two that exist to price the boundary. + *

+ * + *

Where the numbers come from

+ *

+ * Every expectation is derived from the source of Minestom {@code 2026.06.20-26.1.2} before it is + * run, not corrected afterwards until the bar turns green. The dimension is the overworld: twenty-four + * sections, world Y from {@code -64} to {@code 319}, so {@code Heightmap#minHeight} is {@code -65} and + * a column scan that finds nothing walks to the floor. + *

+ * + *

Every count here is a count about blocks

+ *

+ * A section carries a biome palette as well, and a biome is stored per section whether the section + * holds a block or not. A generator which gives the whole chunk a biome therefore needs all + * twenty-four sections, and the saving this class measures is a saving on the sections a generator + * leaves entirely alone. That is not left implicit: the generator cases below come in pairs, one which + * writes blocks and no biomes and one which writes a biome and no blocks, and the second one asserts + * the full twenty-four. + *

+ * + * @author TheMeinerLP + * @version 1.3.1 + * @since 0.4.0 + */ +@DisplayName("What a caller of a Falco chunk makes it allocate") +class SectionMaterialisationTest { + + private static final int SECTIONS = 24; + + private static InstanceContainer container; + + @BeforeAll + static void server() { + if (MinecraftServer.process() == null) { + MinecraftServer.init(); + } + container = MinecraftServer.getInstanceManager().createInstanceContainer(); + } + + private static FalcoChunk chunk() { + return new FalcoChunk(container, 0, 0); + } + + private static int owned(FalcoChunk chunk) { + return chunk.storage().materialisedSections(); + } + + private static Block read(FalcoChunk chunk, int x, int y, int z) { + chunk.lockReadLock(); + try { + return chunk.getBlock(x, y, z); + } finally { + chunk.unlockReadLock(); + } + } + + private static void write(FalcoChunk chunk, int y, Block block) { + chunk.lockWriteLock(); + try { + chunk.setBlock(0, y, 0, block); + } finally { + chunk.unlockWriteLock(); + } + } + + /** + * Forces the chunk packet to be built. + *

+ * {@code Chunk#getFullDataPacket()} hands out a {@code CachedPacket}, which serialises nothing + * until somebody asks it for a packet; calling it alone would measure a field read and would pass + * on a chunk that never serialises at all. {@code SendablePacket#extractServerPacket} is the route + * a player connection takes and is what actually runs {@code FalcoChunk#createChunkPacket}. + *

+ * + * @param chunk the chunk to serialise + */ + private static void serialise(FalcoChunk chunk) { + SendablePacket.extractServerPacket(ConnectionState.PLAY, chunk.getFullDataPacket()); + } + + /** + * Generates the chunk at the origin of a fresh instance and hands it over. + *

+ * The generator cases need an instance rather than the shared container of this class, because + * {@code ChunkGeneration#apply} is the subject and only a {@link FalcoInstance} runs it. The + * instance is unregistered again before the chunk is handed back: it exists for one chunk, and a + * registered instance which nobody unregisters keeps its tick partition for the rest of the run. + *

+ * + * @param generator the generator to run over the chunk + * @return the generated chunk at {@code 0:0} + */ + private static FalcoChunk generated(Generator generator) { + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + + instance.setGenerator(generator); + MinecraftServer.getInstanceManager().registerInstance(instance); + try { + return (FalcoChunk) instance.loadChunk(0, 0).join(); + } finally { + MinecraftServer.getInstanceManager().unregisterInstance(instance); + } + } + + @Test + @DisplayName("a fresh chunk owns nothing") + void testAFreshChunkOwnsNoSection() { + assertEquals(0, owned(chunk())); + } + + @Test + @DisplayName("reading a whole empty chunk owns nothing") + void testReadingOwnsNothing() { + final FalcoChunk chunk = chunk(); + + chunk.lockReadLock(); + try { + for (int y = -64; y < 320; y++) { + chunk.getBlock(0, y, 0); + } + } finally { + chunk.unlockReadLock(); + } + assertEquals(0, owned(chunk)); + } + + /** + * Prices the on-demand heightmap, which is the one saving that could plausibly be paid for twice. + *

+ * A heightmap that is built later is only cheaper if building it later does not build everything + * else with it. The two numbers below separate the two halves of that question: creating the + * carrier costs nothing at all, and the sections are owed to whoever asks the heightmap for a + * height, exactly as before. The remaining cases of this class are the proof that the second half + * did not move — they are unchanged, and a descent that had shifted into the accessor would have + * changed every one of them. + *

+ */ + @Test + @DisplayName("building a heightmap owns nothing, asking it a height owns what the descent walks") + void testTheOnDemandHeightmapOwnsNothingUntilItIsAskedAHeight() { + final FalcoChunk fresh = chunk(); + + assertNotNull(fresh.motionBlockingHeightmap()); + assertNotNull(fresh.worldSurfaceHeightmap()); + + assertEquals(0, owned(fresh), + "a Heightmap is a short[256] and two ints; its constructor reads the dimension of the " + + "instance and touches no section. Building both on demand therefore moves " + + "nothing into the accessor, which is the risk this case exists to rule out"); + + final FalcoChunk asked = chunk(); + + asked.lockReadLock(); + try { + asked.motionBlockingHeightmap().getHeight(0, 0); + } finally { + asked.unlockReadLock(); + } + + assertEquals(SECTIONS, owned(asked), + "and this is what a height costs on a chunk nothing has refreshed: Heightmap#getHeight " + + "falls back to the static Heightmap#getHighestBlockSection, which walks every " + + "section of the chunk through Chunk#getSection until it finds a non-empty " + + "palette - on an empty chunk, all twenty-four. FalcoChunk never takes that " + + "route itself; calculateFullHeightmap starts from highestBlockSection(), " + + "which reads through BlockStorage#view(int). The number is stated so that a " + + "caller which reaches for getHeight on a fresh chunk knows it is buying the " + + "eager layout, and it is unchanged by the heightmaps becoming lazy: the " + + "eager field carried needsRefresh just as the built one does"); + } + + @Test + @DisplayName("one write owns its own section and everything the first heightmap refresh walks over") + void testOneWriteOwnsItsSectionAndTheHeightmapDescent() { + final FalcoChunk chunk = chunk(); + + write(chunk, 64, Block.STONE); + + assertEquals(10, owned(chunk), + "one for the section the block landed in, nine for the heightmap. The first write of " + + "a chunk triggers the full refresh, which starts at world Y 80 - the bottom " + + "of the section above the highest non-empty one, as " + + "Heightmap#getHighestBlockSection computes it - and then runs " + + "Heightmap#refresh(int,int,int) for all 256 columns. That descent reaches " + + "its sections through Chunk#getSection, which materialises, and 255 of the " + + "columns find nothing and walk to the floor: sections 5 down to -4. The " + + "number is 10 and not 1 because the heightmap of Minestom cannot be told to " + + "read instead of to take; if it ever becomes 24 the scan has stopped " + + "starting from highestBlockSection() and the whole stage is worth nothing"); + } + + @Test + @DisplayName("serialising a fresh chunk owns only the floor section") + void testSerialisingAFreshChunkOwnsOnlyTheFloorSection() { + final FalcoChunk chunk = chunk(); + + serialise(chunk); + + assertEquals(1, owned(chunk), + "the packet body and the light data both read through BlockStorage#views() and own " + + "nothing at all; the one section is the heightmap again. An empty chunk has " + + "no non-empty section, so the refresh starts at world Y -64, every column " + + "asks Chunk#getSection(-4) and immediately falls off the bottom of the " + + "world. This is the price of a chunk send: one section, not twenty-four"); + } + + @Test + @DisplayName("serialising a written chunk owns nothing beyond what the write already cost") + void testSerialisingAWrittenChunkOwnsNothingMore() { + final FalcoChunk chunk = chunk(); + + write(chunk, 64, Block.STONE); + final int beforeSend = owned(chunk); + + serialise(chunk); + + assertEquals(beforeSend, owned(chunk), + "the heightmaps were already refreshed by the write, so the send is left with the " + + "serialisation itself - and that is the claim this whole stage rests on: " + + "the network boundary reads through views() and materialises nothing, no " + + "matter how often a chunk is sent"); + assertEquals(10, beforeSend); + } + + @Test + @DisplayName("asking for one section through the Minestom boundary owns exactly that one") + void testGetSectionOwnsOne() { + final FalcoChunk chunk = chunk(); + + chunk.getSection(4); + + assertEquals(1, owned(chunk)); + } + + @Test + @DisplayName("asking for the section list through the Minestom boundary owns the whole chunk") + void testGetSectionsOwnsEverything() { + final FalcoChunk chunk = chunk(); + + chunk.getSections(); + + assertEquals(SECTIONS, owned(chunk), + "this is the price of the boundary and it is stated rather than hidden: a caller " + + "which reaches into the chunk this way makes the lazy layout cost exactly " + + "what the eager one costs"); + } + + @Test + @DisplayName("a copy owns what the original owned") + void testCopyOwnsWhatWasOwned() { + final FalcoChunk chunk = chunk(); + + write(chunk, 64, Block.STONE); + chunk.lockReadLock(); + final Chunk copy; + try { + copy = chunk.copy(container, 1, 1); + } finally { + chunk.unlockReadLock(); + } + + assertEquals(owned(chunk), ((FalcoChunk) copy).storage().materialisedSections(), + "LazySectionBlockStorage#copy() carries the sharing over slot by slot, so a copy is " + + "neither cheaper nor more expensive than what it copied"); + assertEquals(10, owned(chunk)); + } + + @Test + @DisplayName("the first heightmap refresh costs whatever sits below the terrain") + void testTheFirstHeightmapRefreshCostsWhatSitsBelowTheTerrain() { + final FalcoChunk chunk = chunk(); + + write(chunk, 200, Block.STONE); + write(chunk, -64, Block.STONE); + + assertEquals(SECTIONS - 6, owned(chunk), + "this is the known leak and its size is the height of the terrain at the moment of " + + "the first full refresh, not the number of gaps. The block at y=200 makes " + + "Heightmap#getHighestBlockSection stop at section 12, so the scan starts at " + + "world Y 208 and the 255 columns which hold nothing walk from section 13 " + + "down to section -4 through Chunk#getSection: 18 sections. The six that " + + "stay shared are the ones above world Y 223. Heightmap#refresh(int,int,int) " + + "cannot be overridden - it ends in a private setter over a private array - " + + "so this number is asserted rather than fixed, and it must not grow"); + } + + @Test + @DisplayName("the same two blocks cost three sections when the low one is written first") + void testTheOrderOfTheFirstTwoWritesDecidesTheHeightmapCost() { + final FalcoChunk chunk = chunk(); + + write(chunk, -64, Block.STONE); + write(chunk, 200, Block.STONE); + serialise(chunk); + + assertEquals(3, owned(chunk), + "the same two blocks as the case above, in the other order, and the chunk holds a " + + "sixth of the sections. The full refresh runs on the first write, when the " + + "only block sits on the floor, so it starts at world Y -48 and touches " + + "sections -3 and -4; the write at y=200 afterwards only reaches " + + "Heightmap#refresh(int,int,int,Block), which compares heights and never " + + "asks for a section. Sending the chunk adds nothing, because both " + + "heightmaps have stopped needing a refresh. The leak is therefore paid " + + "once, on the first full refresh of a chunk, and a chunk which is written " + + "from the bottom up never pays it in full"); + } + + @Test + @DisplayName("the eager storage owns everything from the start, which is what makes the counts above a saving") + void testTheEagerStorageOwnsEverythingFromTheStart() { + final FalcoChunk eager = new FalcoChunk(container, 0, 0, + new SectionBlockStorage(-4, SECTIONS)); + + assertEquals(SECTIONS, owned(eager), + "the control. Without it every number above could be read as a property of the " + + "counter rather than of the layout"); + + write(eager, 64, Block.STONE); + serialise(eager); + + assertEquals(SECTIONS, owned(eager)); + } + + @Test + @DisplayName("a generator which writes blocks and no biomes owns only the sections it filled") + void testAGeneratorOwnsOnlyWhatItFilled() { + final FalcoChunk chunk = generated(unit -> unit.modifier().fillHeight(-64, 0, Block.STONE)); + + assertEquals(4, owned(chunk), + "stone from y=-64 to y=0 fills exactly four sections; the other twenty hold nothing " + + "and must stay shared. This is the number the whole stage is for: a chunk " + + "which is generated and then owns all twenty-four sections has paid the full " + + "price of the eager layout before the first block of terrain was written. " + + "The four holds under one condition, and the case below states it: this " + + "generator writes blocks and no biomes. A generator which also calls " + + "fillBiome over the chunk unit owns all twenty-four, and correctly so"); + assertEquals(Block.STONE, read(chunk, 0, -64, 0)); + assertEquals(Block.AIR, read(chunk, 0, 0, 0)); + + for (int index = 0; index < 4; index++) { + assertEquals(0, chunk.storage().view(index).blockPalette().bitsPerEntry(), + "a section a generator filled with one state ends in the single value mode. " + + "UnitModifier#fillHeight covering a whole section routes through " + + "SectionModifierImpl#fill to Palette#fill, so this width is what the " + + "generator produced and not what the commit reclaimed"); + } + } + + @Test + @DisplayName("the commit packs the palette a generator left at the direct width") + void testTheCommitPacksWhatTheGeneratorLeftWide() { + final FalcoChunk chunk = generated(unit -> unit.subdivide().get(8).modifier() + .setAllRelative((x, y, z) -> (x + y + z) % 2 == 0 ? Block.STONE : Block.DIRT)); + + assertEquals(1, owned(chunk), + "one section was written and twenty-three were not"); + assertEquals(Block.STONE, read(chunk, 0, 64, 0)); + assertEquals(Block.DIRT, read(chunk, 1, 64, 0)); + + assertEquals(Palette.BLOCK_PALETTE_MIN_BITS, chunk.storage().view(8).blockPalette().bitsPerEntry(), + "two distinct states need four bits, the minimum an indirect block palette has. " + + "PaletteImpl#setAll calls makeDirect() whenever the supplier answered more " + + "than one value, so the generator handed the commit a palette fifteen bits " + + "wide holding two states - 8192 bytes for content that fits in 2048. Without " + + "the optimisation in the commit this section stays at fifteen bits, because " + + "nothing in Minestom ever narrows a palette again"); + } + + /** + * States the condition under which the four of the case above holds, and what happens outside it. + *

+ * {@code UnitModifier#fillBiome} over a chunk unit is the ordinary way to give a chunk a biome, and + * {@code AreaModifierImpl#fillBiome} hands it down to every one of the twenty-four section + * modifiers, each of which calls {@code Palette#fill} on its biome palette. A filled palette whose + * value is not zero answers {@code count()} with its {@code maxSize()}, so the commit sees content + * in every section and materialises every section. That is not a leak: a biome is per section, and + * a section which has to carry one has to exist. The number this stage advertises is therefore a + * number about blocks, and a generator which sets biomes over the whole chunk pays the full eager + * price for the biomes alone. + *

+ *

+ * The case is also the only cover for the second clause of the skip condition. Drop + * {@code biomes().count() == 0} from {@code ChunkGeneration#commitSection} and a section whose sole + * content is a biome is skipped and the biome is dropped in silence; without this case the whole + * suite stays green through that mutation. + *

+ */ + @Test + @DisplayName("a generator which fills biomes owns every section, because a biome needs a section to sit in") + void testAGeneratorWhichFillsBiomesOwnsEverySection() { + // Minestom keeps its Biomes constants package private, so the key comes from the registry. + // Desert rather than plains because an empty biome palette already reads back as id zero, and + // filling with zero would leave count() at zero and prove nothing about the skip. + final RegistryKey desert = MinecraftServer.getBiomeRegistry().getKey(Key.key("minecraft:desert")); + + assertNotNull(desert, "the fixture needs a registered biome"); + assertNotEquals(0, MinecraftServer.getBiomeRegistry().getId(desert), + "the fixture needs a biome whose id is not the one an empty palette reads back"); + + final FalcoChunk chunk = generated(unit -> unit.modifier().fillBiome(desert)); + + assertEquals(SECTIONS, owned(chunk), + "every section carries the biome, so every section exists. This is the condition on " + + "the four of testAGeneratorOwnsOnlyWhatItFilled, stated as a number rather " + + "than left to the reader: the saving of this stage is a saving on the " + + "sections a generator leaves entirely alone, and a chunk wide fillBiome " + + "leaves none"); + assertEquals(desert, chunk.storage().getBiome(0, -64, 0), + "the bottom section holds no block at all, so the biome is the only thing that keeps " + + "it alive; if the commit skips it the biome is gone without a word"); + assertEquals(desert, chunk.storage().getBiome(0, 300, 0)); + } + + /** + * Covers the third clause of the skip condition, which no other case in the repository reaches. + *

+ * A block which needs its own entry — nbt, a handler or a block entity — is collected by + * {@code SectionModifierImpl#handleCache} into {@code GenSection#specials} and written into the + * palette as its state id. For a handler on air that state id is zero, so the block palette of the + * section reports {@code count() == 0} and the specials map is the only evidence that the generator + * touched the section at all. Drop {@code specials().isEmpty()} from the condition and this block + * disappears; the existing special block case, + * {@code FalcoInstanceGeneratorTest#testABlockWhichNeedsItsOwnEntrySurvivesGeneration}, cannot see + * it because a chest raises the palette count on its own. + *

+ */ + @Test + @DisplayName("a section whose only content is a handler on air is committed, not skipped") + void testASectionCarryingOnlyAHandlerOnAirIsCommitted() { + final BlockHandler handler = MinecraftServer.getBlockManager().getHandlerOrDummy("falco:marker"); + final Block markedAir = Block.AIR.withHandler(handler); + + assertEquals(0, markedAir.stateId(), + "the case rests on the state id being the one an empty palette already holds; a " + + "non-zero id would raise the block count and the specials clause would no " + + "longer be the only thing keeping the section alive"); + + final FalcoChunk chunk = generated(unit -> unit.modifier().setBlock(0, 64, 0, markedAir)); + + assertFalse(chunk.storage().shared(8), + "section 8 holds world Y 64. Its palettes are empty and stay empty, so only the " + + "specials map can be the reason it is materialised at all"); + final Block placed = read(chunk, 0, 64, 0); + assertNotNull(placed.handler(), "the handler is the whole content of that section"); + assertEquals("falco:marker", placed.handler().getKey().asString()); + } +} diff --git a/falco-light/build.gradle.kts b/falco-light/build.gradle.kts index 04377d6..808195d 100644 --- a/falco-light/build.gradle.kts +++ b/falco-light/build.gradle.kts @@ -7,7 +7,9 @@ dependencies { compileOnly(libs.adventure.nbt) compileOnly(libs.annotations) compileOnly(libs.minestom) + compileOnly(project(":falco-instance")) + testImplementation(project(":falco-instance")) testImplementation(libs.adventure.nbt) testImplementation(libs.annotations) testImplementation(libs.minestom) diff --git a/falco-light/src/main/java/net/onelitefeather/falco/light/ChunkLightListener.java b/falco-light/src/main/java/net/onelitefeather/falco/light/ChunkLightListener.java new file mode 100644 index 0000000..cbed8db --- /dev/null +++ b/falco-light/src/main/java/net/onelitefeather/falco/light/ChunkLightListener.java @@ -0,0 +1,118 @@ +package net.onelitefeather.falco.light; + +import net.minestom.server.instance.block.Block; +import net.onelitefeather.falco.instance.ChunkLifecycleEvent; +import net.onelitefeather.falco.instance.ChunkLifecycleListener; +import net.onelitefeather.falco.instance.FalcoChunk; +import org.jetbrains.annotations.ApiStatus; + +/** + * The {@link ChunkLightListener} class reports the changes of a chunk to a + * {@link ChunkLightScheduler}, without being that chunk. + *

+ * These three reports used to be three overrides of {@link FalcoLightingChunk}, which meant that + * light occupied the only extension point a chunk had: a class has one superclass, so a server which + * wanted Falco's light and anything else on the same chunk had to pick one. As a listener they + * compose, and the chunk keeps only what genuinely needs to live on it — the cached light packet, + * which is per chunk and cannot be held by a listener registered once for a whole instance. + *

+ *

+ * What is reported is a position and not merely a chunk. {@link #onBlockChange} knows exactly which + * block moved, and handing that on is what lets the engine replay one position instead of searching + * nine chunks; a chunk which arrives from a generator or a loader has no such position to offer, so + * {@link #onLoad} reports a change of unknown extent and pays for one search. + *

+ *

+ * Two of the five transitions are deliberately not implemented. A publish happens before the loaded + * flag of the chunk is set and therefore before {@code ChunkLightScheduler#deliver} would find the + * chunk worth sending to, and an unload needs nothing: the entry of a chunk which left its instance + * is dropped by the next pass that looks for it, which {@code ChunkLightScheduler#compute} states + * where it does it. + *

+ *

+ * One listener belongs to one scheduler and therefore to one instance, exactly like the scheduler it + * reports to. It holds no state of its own beyond that reference, so the same instance can be + * registered on every chunk of that instance. + *

+ *

+ * This type is experimental. The light engine is new and its API may still change. + *

+ * + * @author TheMeinerLP + * @version 1.0.0 + * @since 0.4.0 + */ +@ApiStatus.Experimental +public final class ChunkLightListener implements ChunkLifecycleListener { + + /** + * The scheduler which decides when the light of a chunk is computed. + */ + private final ChunkLightScheduler scheduler; + + /** + * Creates a listener reporting to a scheduler. + * + * @param scheduler the scheduler which decides when the light of a chunk is computed + */ + public ChunkLightListener(ChunkLightScheduler scheduler) { + this.scheduler = scheduler; + } + + /** + * Reports the changed position, which is what lets the light be updated rather than searched. + *

+ * The block is written first and reported afterwards, which is a property of + * {@code FalcoChunk#setBlock} rather than of this class: a pass which reads the block states of + * that chunk between the two either sees the new block and the position, or neither, and never + * the block without the position. + *

+ * + * @param chunk the chunk which received the block + * @param x the block X + * @param y the block Y + * @param z the block Z + * @param block the block which was written + */ + @Override + public void onBlockChange(FalcoChunk chunk, int x, int y, int z, Block block) { + this.scheduler.markChanged(chunk.getInstance(), chunk.getChunkX(), chunk.getChunkZ(), x, y, z); + } + + /** + * Reports the chunk dirty as soon as its instance has taken it. + *

+ * Without this a world that is only ever read would stay black: no block ever changes, so nothing + * would ever ask for the light of a chunk that came straight from a loader or a generator. The + * neighbours are reported with it, because a chunk that appears next to an already lit one can + * send light into it that was not there when it was lit. + *

+ *

+ * The blocks of a freshly generated chunk arrive without passing {@code setBlock}, so this is + * reported as a change of unknown extent and the chunk is lit from its block states once. + *

+ * + * @param event the chunk which finished loading + */ + @Override + public void onLoad(ChunkLifecycleEvent event) { + final FalcoChunk chunk = event.chunk(); + this.scheduler.markChanged(chunk.getInstance(), chunk.getChunkX(), chunk.getChunkZ()); + } + + /** + * Drives the scheduler, once per tick of every chunk it is installed on. + *

+ * A pass has to see every change of the tick before it forms its areas, so the scheduler and not + * this listener decides that only the first chunk of a tick runs one. What matters here is that + * every chunk reports: a listener which only spoke for the chunks holding a block entity would + * leave an instance of ordinary chunks without a heartbeat. + *

+ * + * @param event the chunk which was ticked, and the tick time + */ + @Override + public void onTick(ChunkLifecycleEvent event) { + this.scheduler.onTick(event.chunk().getInstance(), event.time()); + } +} diff --git a/falco-light/src/main/java/net/onelitefeather/falco/light/ChunkLightScheduler.java b/falco-light/src/main/java/net/onelitefeather/falco/light/ChunkLightScheduler.java index e033f40..89c3db8 100644 --- a/falco-light/src/main/java/net/onelitefeather/falco/light/ChunkLightScheduler.java +++ b/falco-light/src/main/java/net/onelitefeather/falco/light/ChunkLightScheduler.java @@ -74,7 +74,7 @@ *

* * @author TheMeinerLP - * @version 1.0.0 + * @version 1.1.0 * @since 0.1.0 */ @ApiStatus.Experimental @@ -463,6 +463,13 @@ public ChunkLightScheduler build() { * instance.setChunkSupplier(scheduler.supplier()); * } *

+ * The chunks it produces are {@link net.onelitefeather.falco.instance.FalcoChunk}s, so they work + * in a {@code FalcoInstance} exactly as they do in an {@code InstanceContainer} — which is what + * US-3.06 was about, since the two used to be mutually exclusive. That also means a caller of + * this method needs {@code falco-instance} on the classpath beside {@code falco-light}; the rest + * of this class does not, see {@link FalcoLightingChunk}. + *

+ *

* Keep the scheduler for exactly the instance it was handed to; see the class comment. *

* diff --git a/falco-light/src/main/java/net/onelitefeather/falco/light/FalcoLightingChunk.java b/falco-light/src/main/java/net/onelitefeather/falco/light/FalcoLightingChunk.java index af89ce9..a9da7be 100644 --- a/falco-light/src/main/java/net/onelitefeather/falco/light/FalcoLightingChunk.java +++ b/falco-light/src/main/java/net/onelitefeather/falco/light/FalcoLightingChunk.java @@ -1,13 +1,11 @@ package net.onelitefeather.falco.light; -import net.minestom.server.instance.DynamicChunk; import net.minestom.server.instance.Instance; -import net.minestom.server.instance.block.Block; -import net.minestom.server.instance.block.BlockHandler; import net.minestom.server.network.packet.server.CachedPacket; import net.minestom.server.network.packet.server.play.UpdateLightPacket; +import net.onelitefeather.falco.instance.FalcoChunk; +import net.onelitefeather.falco.instance.FalcoInstance; import org.jetbrains.annotations.ApiStatus; -import org.jetbrains.annotations.Nullable; /** @@ -23,29 +21,34 @@ * different chunk gets none at all. *

*

- * Why this lives in {@code falco-light} and not in {@code falco-instance}. A replacement for - * {@code LightingChunk} needs the light engine and nothing else — it holds no computation logic of - * its own, it only reports what changed and when the tick happened. Putting it next to - * {@code FalcoInstance} would create a dependency from one published module to another for a type - * that has no relationship to an instance implementation, while putting it here creates no new - * coupling at all. A {@code FalcoInstance} does not need a lighting chunk, and this chunk does not - * need a {@code FalcoInstance}: it works on any {@code Instance}, including the plain - * {@code InstanceContainer} the server ships with. + * Why this needs {@code falco-instance} on the compile path. It used to need nothing but the + * light engine, and that argument stopped holding the moment this class became a + * {@link FalcoChunk}: a chunk cannot be one without the module that defines it. The dependency is + * {@code compileOnly}, so the light engine itself — {@link ChunkLightService}, + * {@code ChunkLightPropagator}, {@link ChunkLightScheduler}, the nibble handling — keeps compiling + * and running with {@code falco-instance} absent, and only this class and {@link ChunkLightListener} + * need it. A consumer who calls {@link ChunkLightScheduler#supplier()} therefore has to put both + * modules on the classpath, which {@code falco-bom} publishes next to one another; a consumer of the + * bare light engine needs neither. An {@code api} dependency was rejected for exactly that + * asymmetry, since it would push {@code falco-instance} onto every server running a plain + * {@code InstanceContainer}. *

*

- * This class holds no computation logic on purpose. Five overrides, and none of them computes - * light. Three report to the scheduler — {@code setBlock} and {@code onLoad} mark the chunk dirty, - * {@code tick} passes the tick on. The other two serve the light packet this chunk sends its - * viewers: {@code invalidate} drops the cached packet, and {@code onLightUpdated} drops it and sends - * a fresh one. Everything else — the dirty set, the areas, the executor, the back pressure — lives - * in {@link ChunkLightScheduler}, so a reader looking for the behaviour finds it in one place rather - * than spread across a chunk and a scheduler. + * This class holds no computation logic on purpose. Two overrides now, and both of them are + * about a packet rather than about light: {@code invalidate} drops the cached light packet and + * {@code onLightUpdated} drops it and sends a fresh one. Everything the chunk used to report — the + * block change, the load, the tick — moved into {@link ChunkLightListener}, and the dirty set, the + * areas, the executor and the back pressure live in {@link ChunkLightScheduler}. A reader looking + * for the behaviour finds it in one place rather than spread across a chunk and a scheduler. *

*

- * What it reports is a position, not just a chunk. {@code setBlock} knows exactly which block - * moved, and handing that on is what lets the engine replay one position instead of searching nine - * chunks. A chunk that arrives from a generator or a loader has no such position to offer, so - * {@code onLoad} reports the change as one of unknown extent and pays for one search of the chunk. + * What the change of superclass bought. A {@link FalcoChunk} allocates no section until + * something writes into one and builds its two heightmaps on the first question rather than in a + * field initialiser, so a fresh chunk of this class retains {@code 840} bytes in 25 objects where + * the {@code DynamicChunk} it used to extend retains {@code 6 848} in 192 — the figures + * {@code ChunkFootprintTest} measures with jol 0.17 on OpenJDK 25.0.3 over an overworld chunk of 24 + * sections. The light itself is unaffected: writing light materialises the sections it writes into, + * exactly as before. *

*

* {@code createLightData} is deliberately not overridden. It reads the sections, and those @@ -59,40 +62,48 @@ * {@code super.isLoaded() && doneInit} and only sets {@code doneInit} in its {@code protected * onLoad()}, so a freshly constructed one reports itself unloaded. Both {@code ChunkBatch} and * {@code AbsoluteBlockBatch} begin with a check on exactly that and return with a warning about an - * unloaded chunk, which makes a batch against such a chunk silently do nothing. Inheriting from - * {@link DynamicChunk} avoids the trap, and rebuilding it here would be a defect, not a feature. + * unloaded chunk, which makes a batch against such a chunk silently do nothing. {@link FalcoChunk} + * has the same property {@code DynamicChunk} has — a freshly constructed chunk reports itself + * loaded — so inheriting from it avoids the trap, and rebuilding it here would be a defect, not a + * feature. *

*

* The batch light gap is closed from this side. {@code AbsoluteBlockBatch#apply} ends by * calling {@code sendLighting()} on every touched chunk that is a {@code LightingChunk} and skips * every other type, so this chunk would never be resent by it. It does not have to be: a batch - * writes through {@code setBlock}, which marks the chunk dirty here, so the following tick computes - * the light of the whole touched region and sends it through {@link #onLightUpdated()}. The result - * arrives one tick later than Minestom's would, and it arrives for the ring around the batch as - * well, which Minestom's path does not manage. + * writes through {@code setBlock}, which reports the position to {@link ChunkLightListener}, so the + * following tick computes the light of the whole touched region and sends it through + * {@link #onLightUpdated()}. The result arrives one tick later than Minestom's would, and it arrives + * for the ring around the batch as well, which Minestom's path does not manage. *

*

* {@code copy} is deliberately not overridden. Minestom copies a chunk into another * instance, and a scheduler serves exactly one. A copy that kept this binding would turn the first * block change placed into it into an {@link IllegalStateException}, because reporting that change - * would try to bind a second instance. The inherited implementation returns a {@link DynamicChunk} - * that carries the cloned sections and therefore the light as a snapshot, with nothing updating it - * afterwards — which is the only correct answer here. Note that this is the opposite of - * {@code FalcoChunk}, which does override {@code copy} so its instance can still unload the copy; - * the two look inconsistent and are not. + * would try to bind a second instance. {@link FalcoChunk#copy(Instance, int, int)} returns a plain + * {@link FalcoChunk} carrying the copied storage and therefore the light as a snapshot, with nothing + * updating it afterwards and no listener on it — which is the only correct answer here, and which + * {@link FalcoInstance} can still unload, unlike the {@code DynamicChunk} the old superclass handed + * back. + *

+ *

+ * Final, where it used to be open. Nothing forced it open but the rule that let it be: a + * class extending a Minestom type is exempt from {@code PublicApiTest#publicClassesAreFinal}, and + * this one no longer extends one. Closing it is also the point of the stage. What a subclass of this + * chunk would have wanted — a second thing happening on a load, a tick or a block write — is exactly + * what {@code FalcoChunk#addLifecycleListener} now gives without a superclass slot, and a subclass + * would take back the one that was just freed. *

*

* This type is experimental. The light engine is new and its API may still change. *

* * @author TheMeinerLP - * @version 1.0.0 + * @version 2.0.0 * @since 0.1.0 */ @ApiStatus.Experimental -public class FalcoLightingChunk extends DynamicChunk implements LightUpdateAware { - - private final ChunkLightScheduler scheduler; +public final class FalcoLightingChunk extends FalcoChunk implements LightUpdateAware { /** * The light packet of this chunk, rebuilt only when somebody asks for it after an invalidation. @@ -107,6 +118,11 @@ public class FalcoLightingChunk extends DynamicChunk implements LightUpdateAware * The scheduler comes first because {@code ChunkSupplier} fixes the trailing three parameters, * which lets {@link ChunkLightScheduler#supplier()} bind it with a method reference. *

+ *

+ * The listener is added here and not by whoever builds the instance, because a chunk which is + * handed out by a supplier has no other moment before its blocks arrive: a generator writes into + * the chunk immediately after this constructor returns. + *

* * @param scheduler the scheduler which decides when the light of this chunk is computed * @param instance the instance this chunk belongs to @@ -115,88 +131,14 @@ public class FalcoLightingChunk extends DynamicChunk implements LightUpdateAware */ public FalcoLightingChunk(ChunkLightScheduler scheduler, Instance instance, int chunkX, int chunkZ) { super(instance, chunkX, chunkZ); - this.scheduler = scheduler; - } - - /** - * Tells the chunk that it has finished loading. - *

- * This is the reachable form of the {@code protected} {@code Chunk#onLoad()} hook, word for word - * what {@code FalcoChunk} offers in {@code falco-instance}. An instance implementation lives in - * another module and another package, so without this it cannot drive the lifecycle of a chunk - * it did not define — which is what kept a lighting chunk and {@code FalcoInstance} from being - * used together. - *

- *

- * Call it once, after the chunk is part of the instance and its tick partition exists. The - * light of the chunk is reported dirty from here, so calling it earlier would mark a chunk the - * instance cannot yet hand out. - *

- */ - public void markLoaded() { - onLoad(); - } - - /** - * Tells the chunk that it is no longer part of its instance. - *

- * This is the reachable form of the {@code protected} {@code Chunk#unload()} hook. It clears the - * loaded flag that every {@code ChunkUtils#isLoaded} check in Minestom reads; a chunk that is - * never marked here stays alive for anyone holding a reference to it. - *

- */ - public void markUnloaded() { - unload(); + addLifecycleListener(new ChunkLightListener(scheduler)); } /** - * Reports the changed position, which is what lets the light be updated rather than searched. - *

- * The block is written first and reported afterwards, so a pass which reads the block states of - * this chunk between the two either sees the new block and the position, or neither, and never - * the block without the position. - *

+ * Drops the cached light packet along with everything else this chunk derived from its blocks. * - * @param x the x coordinate of the block - * @param y the y coordinate of the block - * @param z the z coordinate of the block - * @param block the block to place - * @param placement the placement rule of the block, or null if there is none - * @param destroy the destroy rule of the replaced block, or null if there is none + * @see FalcoChunk#invalidate() */ - @Override - public void setBlock(int x, int y, int z, Block block, - @Nullable BlockHandler.Placement placement, - @Nullable BlockHandler.Destroy destroy) { - super.setBlock(x, y, z, block, placement, destroy); - this.scheduler.markChanged(this.instance, this.chunkX, this.chunkZ, x, y, z); - } - - /** - * Reports this chunk dirty as soon as the instance has taken it. - *

- * Without this a world that is only ever read would stay black: no block ever changes, so - * nothing would ever ask for the light of a chunk that came straight from a loader or a - * generator. The neighbours are reported with it, because a chunk that appears next to an - * already lit one can send light into it that was not there when it was lit. - *

- *

- * The blocks of a freshly generated chunk arrive without passing {@code setBlock}, so this is - * reported as a change of an unknown extent and the chunk is lit from its block states once. - *

- */ - @Override - protected void onLoad() { - super.onLoad(); - this.scheduler.markChanged(this.instance, this.chunkX, this.chunkZ); - } - - @Override - public void tick(long time) { - super.tick(time); - this.scheduler.onTick(this.instance, time); - } - @Override public void invalidate() { super.invalidate(); @@ -206,12 +148,17 @@ public void invalidate() { /** * Sends the freshly computed light of this chunk to everybody who is looking at it. *

- * This is the step Minestom has no hook for. {@code DynamicChunk#invalidate} drops the cached - * full chunk packet, which carries the light inside it, but that only reaches a player who - * receives the chunk afterwards — somebody already standing in it would see the old light until - * they reload. {@code LightingChunk} solves this with a resend timer and a private packet cache; - * the same result is reached here through the one piece of that machinery which is reachable - * from the outside, the {@code protected createLightData}. + * This is the step Minestom has no hook for. {@code Chunk#invalidate} drops the cached full chunk + * packet, which carries the light inside it, but that only reaches a player who receives the + * chunk afterwards — somebody already standing in it would see the old light until they reload. + * {@code LightingChunk} solves this with a resend timer and a private packet cache; the same + * result is reached here through the one piece of that machinery which is reachable from the + * outside, the {@code protected createLightData}. + *

+ *

+ * This is also why the packet cache stays on the chunk while the three reports moved to a + * listener: it is per chunk, and a listener registered once for a whole instance has nowhere to + * keep it. *

*/ @Override diff --git a/falco-light/src/test/java/net/onelitefeather/falco/light/FalcoLightingChunkTest.java b/falco-light/src/test/java/net/onelitefeather/falco/light/FalcoLightingChunkTest.java index 2897790..cf721ea 100644 --- a/falco-light/src/test/java/net/onelitefeather/falco/light/FalcoLightingChunkTest.java +++ b/falco-light/src/test/java/net/onelitefeather/falco/light/FalcoLightingChunkTest.java @@ -4,13 +4,21 @@ import net.minestom.server.instance.Instance; import net.minestom.server.instance.batch.AbsoluteBlockBatch; import net.minestom.server.instance.block.Block; +import net.minestom.server.world.DimensionType; import net.minestom.testing.Env; import net.minestom.testing.extension.MicrotusExtension; +import net.onelitefeather.falco.instance.ChunkLifecycleEvent; +import net.onelitefeather.falco.instance.ChunkLifecycleListener; +import net.onelitefeather.falco.instance.FalcoChunk; +import net.onelitefeather.falco.instance.FalcoInstance; +import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.extension.ExtendWith; +import java.util.UUID; import java.util.function.BooleanSupplier; import java.util.concurrent.TimeUnit; +import java.util.concurrent.atomic.AtomicInteger; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertFalse; @@ -32,9 +40,16 @@ * must not inherit or rebuild that. And {@code AbsoluteBlockBatch#apply} resends light only for a * {@code LightingChunk}, so a batch has to be covered here rather than assumed to work. *

+ *

+ * The four cases at the end are US-3.06 and they are the reason this module now sees + * {@code falco-instance}. Everything above them drives the chunk through an + * {@code InstanceContainer}, which is the arm that reaches the {@code protected} hooks directly; + * those four add the {@code FalcoInstance} arm, the second listener beside the light, and the proof + * that the storage stayed lazy when the superclass changed. + *

* * @author TheMeinerLP - * @version 1.0.0 + * @version 2.0.0 * @since 0.1.0 */ @ExtendWith(MicrotusExtension.class) @@ -278,4 +293,136 @@ void testTheChunkTellsTheSchedulerAboutEveryTickOnce(Env env) { assertFalse(scheduler.isDirty(0, 0), "and the following tick has to clear it again"); } + + @Test + @DisplayName("is a Falco chunk, so a Falco instance can hold it") + void testTheLightingChunkIsAFalcoChunk(Env env) { + final ChunkLightScheduler scheduler = new ChunkLightScheduler(new ChunkLightService(), Runnable::run, 16); + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + instance.setChunkSupplier(scheduler.supplier()); + + final Chunk chunk = instance.loadChunk(0, 0).join(); + + assertInstanceOf(FalcoLightingChunk.class, chunk); + assertInstanceOf(FalcoChunk.class, chunk, + "the whole point of US-3.06: one chunk instance serves the lifecycle and the light"); + assertTrue(chunk.isLoaded()); + instance.unloadChunk(chunk); + assertFalse(chunk.isLoaded(), "a Falco instance can reach the unload hook of this chunk"); + } + + @Test + @DisplayName("keeps its storage lazy, so it costs what stage 2 measured") + void testTheLightingChunkHoldsNoSections(Env env) { + final ChunkLightScheduler scheduler = new ChunkLightScheduler(new ChunkLightService(), Runnable::run, 16); + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + + final FalcoChunk chunk = new FalcoLightingChunk(scheduler, instance, 0, 0); + + assertEquals(0, chunk.storage().materialisedSections(), + "a lighting chunk is a Falco chunk now, so it starts with no section of its own either"); + assertFalse(chunk.hasHeightmaps()); + } + + @Test + @DisplayName("lets a second extension sit beside the light") + void testASecondListenerFitsBesideTheLight(Env env) { + final ChunkLightScheduler scheduler = new ChunkLightScheduler(new ChunkLightService(), Runnable::run, 16); + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + final AtomicInteger ticks = new AtomicInteger(); + final FalcoChunk chunk = new FalcoLightingChunk(scheduler, instance, 0, 0); + + chunk.markLoaded(); + + assertTrue(scheduler.isDirty(0, 0), "the light is on this chunk before the second listener is"); + + chunk.addLifecycleListener(new ChunkLifecycleListener() { + + @Override + public void onTick(ChunkLifecycleEvent event) { + ticks.incrementAndGet(); + } + }); + chunk.tick(1L); + + assertEquals(1, ticks.get(), + "before this stage the light occupied the only extension point a chunk had"); + assertFalse(scheduler.isDirty(0, 0), + "and the same tick still drove the light pass, so the two sit beside each other"); + } + + /** + * Both extensions arrive on a chunk the instance built, not only on one built by hand. + *

+ * The listener of the light comes from the constructor of the chunk and the second one from + * {@code ChunkLifecycle#addListener}, so this is the case where the two registrations meet + * without either knowing about the other — which is the whole of US-3.06 in one method. + *

+ */ + @Test + @DisplayName("carries the light and an instance-wide listener on the same loaded chunk") + void testAnInstanceWideListenerArrivesBesideTheLight(Env env) { + final ChunkLightService service = new ChunkLightService(); + final ChunkLightScheduler scheduler = new ChunkLightScheduler(service, Runnable::run, 16); + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + instance.setChunkSupplier(scheduler.supplier()); + final AtomicInteger loads = new AtomicInteger(); + final AtomicInteger writes = new AtomicInteger(); + instance.lifecycle().addListener(new ChunkLifecycleListener() { + + @Override + public void onLoad(ChunkLifecycleEvent event) { + loads.incrementAndGet(); + } + + @Override + public void onBlockChange(FalcoChunk chunk, int x, int y, int z, Block block) { + writes.incrementAndGet(); + } + }); + + final Chunk chunk = instance.loadChunk(0, 0).join(); + place(chunk, 8, 40, 8, Block.GLOWSTONE); + chunk.tick(1L); + + assertEquals(1, loads.get(), "the foreign listener heard the load"); + assertEquals(1, writes.get(), "and the block write"); + assertEquals(15, service.blockLightAt(chunk, 8, 40, 8), + "while the light of the same chunk was computed by the listener it did not displace"); + } + + /** + * The load report survives a plain {@code InstanceContainer}, which drives another hook. + *

+ * {@code InstanceContainer#retrieveChunk} calls the {@code protected Chunk#onLoad()} of the chunk + * directly, while {@code FalcoInstance} goes through {@code FalcoChunk#markLoaded()}. Two arms, + * one report: a lighting chunk which only heard the second would leave every world running on a + * container black, and that container is what the rest of this suite is built on. + *

+ */ + @Test + @DisplayName("reports its load through both instance implementations") + void testTheLoadReportReachesTheSchedulerFromEitherInstance(Env env) { + final ChunkLightScheduler container = new ChunkLightScheduler(new ChunkLightService(), Runnable::run, 16); + final Instance plain = env.createEmptyInstance(); + plain.setChunkSupplier(container.supplier()); + + plain.loadChunk(4, 4).join(); + + assertTrue(container.isDirty(4, 4), + "an InstanceContainer reaches the protected onLoad hook, and that has to report too"); + + final ChunkLightScheduler falco = new ChunkLightScheduler(new ChunkLightService(), Runnable::run, 16); + final FalcoInstance instance = new FalcoInstance(UUID.randomUUID(), DimensionType.OVERWORLD); + env.process().instance().registerInstance(instance); + instance.setChunkSupplier(falco.supplier()); + + instance.loadChunk(4, 4).join(); + + assertTrue(falco.isDirty(4, 4), "and a FalcoInstance reaches markLoaded, which has to report as well"); + } } diff --git a/gradle/api-breaks.properties b/gradle/api-breaks.properties new file mode 100644 index 0000000..cd800df --- /dev/null +++ b/gradle/api-breaks.properties @@ -0,0 +1,28 @@ +# Deliberately accepted breaks of binary compatibility. +# +# Every entry here switches off the japicmp check for one type, which means nothing about that type +# is compared any more -- not the break named below and not any further break that lands later. An +# entry is therefore a debt, not a decision that stays true. The `baseline` key below binds the whole +# file to the released version the exceptions were judged against; the build fails if it drifts from +# `apiBaselineVersion` in gradle.properties. That failure is the point: after the next release +# somebody has to look at each entry again and delete the ones the new baseline has absorbed. +# +# Format: .classExcludes = [, ...] + +baseline = 0.3.0 + +# net.onelitefeather.falco.light.FalcoLightingChunk +# +# The class became `final` and now extends net.onelitefeather.falco.instance.FalcoChunk instead of +# Minestom's DynamicChunk (US-3.06 of docs/superpowers/specs/2026-08-01-falco-instance-chunk-design.md). +# `final` is a real break: anyone who subclassed it no longer can. It is deliberate -- the light +# engine and the chunk lifecycle had to end up on one instance, which is what the whole storage +# rewrite was for -- and admissible because the package documents every public type in it as +# experimental. +# +# japicmp additionally reports `setBlock(int, int, int, Block, BlockHandler$Placement, +# BlockHandler$Destroy)` and `tick(long)` as removed. Both are wrong. The methods are still public on +# FalcoChunk and callers keep them by inheritance; japicmp cannot see that because FalcoChunk lives +# in another module and `ignoreMissingClasses` is on, so an inherited member looks removed. Verified +# with `javap -p` on falco-instance's FalcoChunk.class -- both are `public` there. +falco-light.classExcludes = net.onelitefeather.falco.light.FalcoLightingChunk diff --git a/settings.gradle.kts b/settings.gradle.kts index 6831c25..38729a0 100644 --- a/settings.gradle.kts +++ b/settings.gradle.kts @@ -38,6 +38,8 @@ dependencyResolutionManagement { version("japicmpPlugin", "0.4.6") version("adventureBom", "5.1.1") version("archunit", "1.4.2") + version("jol", "0.17") + version("flare", "2.0.1") plugin("jmh", "me.champeau.jmh").versionRef("jmhPlugin") plugin("japicmp", "me.champeau.gradle.japicmp").versionRef("japicmpPlugin") @@ -48,6 +50,7 @@ dependencyResolutionManagement { library("slf4j.simple", "org.slf4j", "slf4j-simple").versionRef("slf4j") library("annotations", "org.jetbrains", "annotations").versionRef("annotations") library("fastutil", "it.unimi.dsi", "fastutil").version("8.5.18") + library("flare.fastutil", "space.vectrix.flare", "flare-fastutil").versionRef("flare") library("minestom", "net.minestom", "minestom").withoutVersion() library("adventure.nbt", "net.kyori", "adventure-nbt").withoutVersion() library("adventure.bom", "net.kyori", "adventure-bom").versionRef("adventureBom") @@ -58,6 +61,7 @@ dependencyResolutionManagement { library("junit.platform.launcher", "org.junit.platform", "junit-platform-launcher").withoutVersion() library("jmh.core", "org.openjdk.jmh", "jmh-core").versionRef("jmh") + library("jol.core", "org.openjdk.jol", "jol-core").versionRef("jol") } } }