Implement M5.4 bounded compact chunk ownership
This commit is contained in:
+7
-1
@@ -34,7 +34,7 @@ target_include_directories(evo_simulation PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/in
|
||||
target_compile_features(evo_simulation PUBLIC cxx_std_23)
|
||||
evo_owned_target(evo_simulation)
|
||||
|
||||
add_library(evo_world STATIC src/world/coordinates.cpp src/world/generation.cpp)
|
||||
add_library(evo_world STATIC src/world/coordinates.cpp src/world/generation.cpp src/world/chunks.cpp)
|
||||
add_library(evo::world ALIAS evo_world)
|
||||
target_include_directories(evo_world PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/include")
|
||||
target_compile_features(evo_world PUBLIC cxx_std_23)
|
||||
@@ -71,6 +71,12 @@ evo_owned_target(evo-sim)
|
||||
|
||||
include(CTest)
|
||||
if(BUILD_TESTING)
|
||||
add_executable(evo-world-chunk-tests tests/world_chunk_tests.cpp)
|
||||
target_link_libraries(evo-world-chunk-tests PRIVATE evo::world)
|
||||
evo_owned_target(evo-world-chunk-tests)
|
||||
add_test(NAME world-chunk-contracts COMMAND evo-world-chunk-tests)
|
||||
set_tests_properties(world-chunk-contracts PROPERTIES TIMEOUT 60)
|
||||
|
||||
add_executable(evo-world-generation-tests tests/world_generation_tests.cpp)
|
||||
target_link_libraries(evo-world-generation-tests PRIVATE evo::world)
|
||||
evo_owned_target(evo-world-generation-tests)
|
||||
|
||||
@@ -16,6 +16,7 @@ network service. Dev verification manifests are separate from the simulation.
|
||||
- [Architecture decisions and proposals](docs/adr/README.md)
|
||||
- [Actionable milestones 0–4 and later gates](docs/ROADMAP.md)
|
||||
- [Open design questions](docs/architecture/OPEN_QUESTIONS.md)
|
||||
- [Bounded chunk ownership](docs/world/CHUNK_OWNERSHIP.md)
|
||||
- [Versioned abiotic base generation](docs/world/BASE_GENERATION.md)
|
||||
- [Actual validation results](docs/engineering/VALIDATION.md)
|
||||
- [Current delivery status and next steps](docs/STATUS.md)
|
||||
|
||||
+3
-1
@@ -262,7 +262,9 @@ M5.2 is complete: [ADR-0043](adr/0043-chunk-layout.md) selects 16-cube
|
||||
uniform/palette/dense storage from the [comparison](engineering/CHUNK_LAYOUT_EVALUATION.md).
|
||||
M5.3 is complete under [ADR-0044](adr/0044-abiotic-generation.md):
|
||||
[versioned abiotic generation](world/BASE_GENERATION.md) with frozen reference fixtures.
|
||||
Next is 5.4: bounded sparse active chunk ownership and compact resident storage.
|
||||
M5.4 is complete under [ADR-0045](adr/0045-bounded-chunk-ownership.md):
|
||||
[bounded ownership](world/CHUNK_OWNERSHIP.md), compact storage, validated revision tokens
|
||||
and dirty eviction refusal. Next is 5.5: accounted transactional terrain edits.
|
||||
|
||||
**Decisions still open:** final spherical layout, region dimensions, adaptive LOD,
|
||||
field quantization beyond the initial experiment, hydrology and surface extraction.
|
||||
|
||||
+9
-2
@@ -7,7 +7,7 @@ persistent simulation server. The founding vision remains unchanged.
|
||||
## Completed implementation
|
||||
|
||||
- Vision, architectural pillars, risks, open-question register, architecture
|
||||
diagrams, biological contracts, engineering constitution and 44 ADRs.
|
||||
diagrams, biological contracts, engineering constitution and 45 ADRs.
|
||||
Proposed/deferred choices remain distinct from accepted proof decisions.
|
||||
- M0–M4 task breakdowns with dependencies, acceptance evidence and risks,
|
||||
plus M5–M14 gates in [ROADMAP.md](ROADMAP.md).
|
||||
@@ -61,7 +61,7 @@ for the bounded proof; the general production ECS remains a later measured choic
|
||||
|
||||
| Priority | Work | Completion evidence |
|
||||
|---|---|---|
|
||||
| 1 | M5.4 sparse active chunk ownership | Bounded compact storage, regeneration, immutable revisioned views and dirty eviction refusal |
|
||||
| 1 | M5.5 accounted terrain edits | Transaction identity, revisions, matter destinations, atomic changes and retry validation |
|
||||
| Research | Improve aggregate fidelity and measure Linux/target-host costs | M4.6 found no qualifying width; see the aggregate budget report |
|
||||
| 2 | Revisit the ADR-0031/0032 reproduction cost model | Reproduction is affordable only at the genome schema's floor; decide whether that is intended before M4 builds cohorts on it |
|
||||
| Delivery gate | Add/update the dev workload when a deployable increment needs it; Argo is ready | Observe Job/pod completion separately from image publication; no World0 changes |
|
||||
@@ -561,3 +561,10 @@ Added pure seed/address/version generation, a bounded inert material table and
|
||||
compatibility and storage boundaries. Twelve independent reference goldens and
|
||||
signed seam/query-order tests freeze v1. No gameplay, persistence or deployment
|
||||
was added. Next: M5.4 sparse active chunk ownership.
|
||||
|
||||
## M5.4 bounded active chunk ownership
|
||||
|
||||
Added fixed-slot, budgeted ChunkStore and immutable uniform/palette/dense CompactCells.
|
||||
Revision tokens reject stale and foreign reads. Clean chunks regenerate; dirty pins
|
||||
refuse eviction. [Ownership contract](world/CHUNK_OWNERSHIP.md) documents memory/lifetime
|
||||
limits and the absence of cell edits or durability. Next: M5.5 accounted terrain edits.
|
||||
|
||||
@@ -0,0 +1,63 @@
|
||||
# ADR-0045: Bounded local chunk ownership
|
||||
|
||||
## Status
|
||||
Accepted for M5.4. Single local owner, not distributed region authority or durability.
|
||||
|
||||
## Context
|
||||
M5.3 produces reproducible base cells; ADR-0043 selects compact 16-cube storage.
|
||||
Address extent must not drive allocation. Eviction must not lose pending dirty state.
|
||||
|
||||
## Decision
|
||||
Use a noncopyable/nonmovable ChunkStore created with a fixed slot count (1..4096),
|
||||
byte budget and immutable BaseDescriptor. A fixed directory bounds metadata and
|
||||
linear lookup; no implicit eviction, threads or global cache. Loading an absent
|
||||
chunk regenerates base data. Existing loads are idempotent. Missing capacity returns
|
||||
backpressure and leaves prior state unchanged. Allocation exceptions reach the host.
|
||||
|
||||
CompactCells is an immutable value with uniform, byte-palette (<=256 distinct keys),
|
||||
or dense representation. Keys include material and fill. Palette order is first
|
||||
X-fast occurrence. Packed byte indexes share one exactly-sized uint32 array with
|
||||
keys; this is an in-memory implementation, not a wire format. Uniform has no payload
|
||||
allocation. Dense contains 4096 uint32 values. Build publishes only after success.
|
||||
|
||||
Charge sizeof(store), all directory entries, owned payload bytes, and 17 KiB reserved
|
||||
for construction scratch (4096 logical words plus 256 palette keys). Check budget
|
||||
before allocating payload. Allocator headers/runtime stack/caller buffers are outside
|
||||
this accounted budget; report it as accounted bytes, never RSS. Array element counts
|
||||
are exact, no vector growth. The standalone compact factory is outside store budgets.
|
||||
|
||||
Views contain owner, slot and monotonic incarnation/revision token; reads revalidate
|
||||
before access and return copied cells, never dangling spans. Views must not outlive
|
||||
their store. Store is immovable; foreign-store views fail. Successful load and first
|
||||
dirty marking consume nonwrapping tokens; exhaustion rejects changes. Evict/reload
|
||||
cannot revive an old view. Revision tokens are local, not durable edit revisions.
|
||||
|
||||
mark_dirty is conservative pre-write pinning, changes no geometry and invalidates
|
||||
old views. Repeated marking of the current dirty view is idempotent. There is no
|
||||
mark-clean, overwrite, or edit API: M5.5 introduces accounted transactions; later
|
||||
persistence must prove durable coverage before clearing dirty state. Explicit eviction
|
||||
requires a current clean view. Destruction is a host shutdown boundary, not durable
|
||||
storage; the host must not destroy a store with unsaved changes in a running world.
|
||||
|
||||
## Alternatives Considered
|
||||
Automatic LRU hides eviction decisions and requires pin lifetime accounting.
|
||||
Shared snapshots can retain unbudgeted payloads. Raw spans invite dangling reads.
|
||||
Maps complicate allocator accounting; linear fixed slots suffice for this bounded gate.
|
||||
|
||||
## Benefits
|
||||
Bounded metadata/payloads, reproducible regeneration and explicit stale/dirty refusal.
|
||||
No edit or persistence shortcut leaks into the geometry library.
|
||||
|
||||
## Costs
|
||||
Linear lookup, reconstruction scratch reservation and copied point reads. No concurrent
|
||||
mutation support, auto eviction, persistence or dirty recovery yet.
|
||||
|
||||
## Risks
|
||||
Accounted bytes exclude allocator overhead and are not an OS ceiling. Owner lifetime
|
||||
is a caller obligation. Dirty pinning can exhaust capacity intentionally; host must
|
||||
apply backpressure rather than dropping state. Larger workloads require measurement.
|
||||
|
||||
## Consequences
|
||||
Test far-apart chunks, uniform/palette/dense equality, exact budget boundaries,
|
||||
slot exhaustion, invalid input, stale/foreign views and dirty eviction refusal.
|
||||
Retain existing generator goldens and simulation formats. Next is M5.5.
|
||||
@@ -47,3 +47,5 @@ design. No unadopted candidate is a link dependency of the proof.
|
||||
- [ADR-0043: Bounded chunk layout](0043-chunk-layout.md) - accepted for M5; 16-cube uniform/palette/dense geometry.
|
||||
|
||||
- [ADR-0044: Abiotic generation](0044-abiotic-generation.md) - accepted for M5.3 synthetic integer base, version retention and material table.
|
||||
|
||||
- [ADR-0045: Bounded chunk ownership](0045-bounded-chunk-ownership.md) - accepted for M5.4 local memory, revision tokens and dirty eviction guards.
|
||||
|
||||
@@ -124,3 +124,11 @@ chunk ownership/allocation limits remain M5.4; optional chemistry pages remain M
|
||||
16-cube queries. Synthetic abiotic strata use global integer addresses and create no
|
||||
life. Unsupported versions fail explicitly. Temporary logical output is not resident
|
||||
storage; bounded chunk ownership/eviction is M5.4. There is no persistence or mesher.
|
||||
|
||||
## Implemented M5.4 ownership boundary
|
||||
|
||||
[ADR-0045](../adr/0045-bounded-chunk-ownership.md) adds compact immutable cells and a
|
||||
fixed-slot, byte-budgeted local store. [The contract](../world/CHUNK_OWNERSHIP.md)
|
||||
specifies construction scratch accounting, current-revision read tokens, regeneration
|
||||
and dirty eviction refusal. No database, distributed lease or durable acknowledgement
|
||||
is implied. Cell edits remain M5.5 and persistence M5.6/5.7.
|
||||
|
||||
@@ -1471,3 +1471,34 @@ stratigraphy, known/unknown materials, version/edge rejection and extreme addres
|
||||
Fingerprint bytes are explicitly little endian logical fields. Linux CI and UBSan
|
||||
were not run locally; no cross-platform execution result is claimed. No deployment
|
||||
or World0 state change occurred. Next: M5.4 bounded sparse chunk ownership.
|
||||
|
||||
## M5.4 bounded chunk ownership - 2026-09-26
|
||||
|
||||
Added CompactCells, a fixed-slot ChunkStore, revision-validated read tokens and
|
||||
conservative dirty pinning under ADR-0045. No cell edit, persistence, distributed
|
||||
lease or clean acknowledgement API was introduced. Existing goldens remain unchanged.
|
||||
|
||||
Executed on Windows x64 / MSVC 19.44:
|
||||
|
||||
- `tools/windows-check.ps1 -Preset release -Action check`: 43/43 CTest passed.
|
||||
- `tools/windows-check.ps1 -Preset analysis -Action check`: clang-tidy 19 build and
|
||||
43/43 CTest passed.
|
||||
- `tools/windows-check.ps1 -Preset asan -Action check`: 43/43 CTest passed.
|
||||
- `tools/windows-check.ps1 -Preset release -Action format`: passed.
|
||||
- `git diff --check`: passed.
|
||||
|
||||
The initial test oracle mixed unsigned local offsets with a negative integer literal;
|
||||
corrected to explicit int64 arithmetic. Analysis required explicit optional checks
|
||||
at reads/eviction and identified an integer-width expression in the test. One narrow
|
||||
use-after-move suppression exercises the explicitly guaranteed empty-void source.
|
||||
Final checks above ran after those corrections.
|
||||
|
||||
Coverage includes palette counts through 256 then dense fallback, full logical cell
|
||||
equality, material/fill distinctions, move validity, extreme/far addresses, exact
|
||||
accounted budget boundaries, failed-load state preservation, slot pressure, clean
|
||||
regeneration, stale/foreign tokens and dirty eviction refusal. Counter exhaustion is
|
||||
guarded but not injected; no allocation-failure fault injector is claimed. Memory
|
||||
accounting excludes allocator/runtime overhead and is not an RSS cap.
|
||||
|
||||
Linux CI/UBSan and target-host performance have not been run locally. No deployment
|
||||
or World0 change occurred. Next: M5.5 accounted transactional edits.
|
||||
|
||||
@@ -0,0 +1,89 @@
|
||||
# M5.4 bounded active chunks
|
||||
|
||||
Implemented by `evo::world`, header `evo/world/chunks.hpp`.
|
||||
[ADR-0045](../adr/0045-bounded-chunk-ownership.md) scopes local ownership; this is
|
||||
not a region lease, distributed authority mechanism or durable store.
|
||||
|
||||
## Contract
|
||||
|
||||
Create a store with one immutable BaseDescriptor, 1..4096 slots and an explicit
|
||||
accounted-byte budget. All operations are single-owner/sequential; callers must not
|
||||
race reads against mutation. World/frame identity belongs to the containing host.
|
||||
Different stores are separate local domains; revision numbers are not globally unique.
|
||||
The owning unique_ptr may move, but the store itself cannot move or copy.
|
||||
|
||||
| Operation | Success | Refusal / invariant |
|
||||
|---|---|---|
|
||||
| minimum_bytes(slots) | Store object + fixed directory + 17 KiB scratch reservation | Invalid slot count rejected before multiplication |
|
||||
| create | Empty store with validated descriptor | Invalid config/version/budget before directory allocation |
|
||||
| load(address) | Return current token or regenerate and publish one base chunk | Invalid address, slot or byte exhaustion, revision exhaustion; no existing state changes |
|
||||
| view(address) | Token for loaded address | Missing is explicit; no implicit load |
|
||||
| read(view, local) | Copy one CellSample | Foreign/stale token or out-of-range local cell; no raw storage pointer |
|
||||
| mark_dirty(view) | Pin chunk, invalidate previous token, return current token | Stale token or revision exhaustion; repeat on current dirty token is idempotent |
|
||||
| evict(view) | Free clean payload and directory slot | Stale or dirty token rejected; no auto eviction |
|
||||
|
||||
Views contain owner/slot/revision internally. They are read tokens, not immutable
|
||||
historical snapshots: every read checks current ownership and revision. Old tokens
|
||||
fail after dirty marking or eviction/reload. They must not outlive the store, including
|
||||
an object later allocated at the same address. They cannot authorize persistence or
|
||||
cross-process operations. Epoch exhaustion is checked before increment; no wraparound.
|
||||
|
||||
Dirty marking currently changes only lifecycle metadata, not geometry. There is no
|
||||
clear-dirty or cell-edit API. M5.5 must introduce accounted edit transactions; M5.6/5.7
|
||||
must establish durable revision coverage before permitting cleanup. Destruction at
|
||||
host shutdown frees memory and is not a save operation. No production host should
|
||||
use this in-memory store as its sole durable copy of changes.
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
Absent --> Clean: load, budget available
|
||||
Clean --> Absent: explicit current-view eviction
|
||||
Clean --> Dirty: conservative pin, new revision
|
||||
Dirty --> Dirty: repeated current-view pin
|
||||
```
|
||||
|
||||
Dirty-to-Absent is deliberately unavailable. Capacity pressure returns to the host.
|
||||
It cannot regenerate modified data to make room.
|
||||
|
||||
## Representation and budgets
|
||||
|
||||
CompactCells accepts exactly 4096 validated CellSample values. It is immutable and
|
||||
move-only; moves reset the source to uniform void. Material keys and fills both
|
||||
participate in equality. This geometry utility checks structural cells, not material
|
||||
table membership or resource authority. ChunkStore loads only M5.3 table-valid base.
|
||||
|
||||
- Uniform: one inline word, zero allocated payload bytes.
|
||||
- Palette: first-occurrence keys (2..256), plus 4096 byte indexes, stored as keys
|
||||
followed by 1024 packed uint32 index words. Payload = 4*K+4096 bytes.
|
||||
- Dense: 4096 uint32 words = 16384 bytes after the 257th distinct key.
|
||||
|
||||
Logical words combine material low 16 bits and fill high 16 bits. Native arrays are
|
||||
not a wire format. M5.6 must specify canonical serialization independently.
|
||||
|
||||
Fixed directory bytes include optional payload objects and lifecycle metadata for
|
||||
all configured slots, occupied or not. Accounted bytes add exact allocated payload
|
||||
array element sizes plus a permanent 17 KiB allowance for load construction scratch:
|
||||
4096 logical words and 256 palette keys. Load generates through point queries to avoid
|
||||
an extra dense vector, computes required payload before allocation, then publishes
|
||||
without throwing. On allocator failure existing state is unchanged; allocation
|
||||
exceptions propagate to the host. Clean eviction subtracts payload only.
|
||||
|
||||
The allowance remains charged when no load runs. Allocator headers/cookies, ordinary
|
||||
call frames, caller buffers and OS runtime are excluded: this is not RSS or an OS
|
||||
memory cap. Standalone CompactCells creation is outside a store's budget. It uses the
|
||||
same bounded scratch plus output, with no budget parameter. Future replacement/edit
|
||||
operations must budget old and new buffers simultaneously; they cannot inherit a
|
||||
claim of in-place promotion from this immutable implementation.
|
||||
|
||||
## Verification and next boundary
|
||||
|
||||
CTest `world-chunk-contracts` checks distinct counts 1/2/255/256/257/4096, every stored
|
||||
sample, material/fill distinction, invalid lengths/indexes, moved-from validity,
|
||||
far-apart addresses, clean regeneration, slot and byte backpressure, stale and foreign
|
||||
tokens, conservative dirty pinning and rejection without changing resident state.
|
||||
Existing generator goldens remain active. Counter exhaustion is guarded in code but
|
||||
not forced via a public test-only state injection API.
|
||||
|
||||
M5.5 adds transaction IDs, payload identity, expected revisions, material destinations
|
||||
and atomic edits. No transactional edit, snapshot, crash recovery, threading, automatic
|
||||
LRU, renderer or Kubernetes integration is provided by M5.4.
|
||||
@@ -0,0 +1,102 @@
|
||||
#pragma once
|
||||
#include "evo/world/generation.hpp"
|
||||
#include <cstddef>
|
||||
#include <cstdint>
|
||||
#include <expected>
|
||||
#include <memory>
|
||||
#include <span>
|
||||
|
||||
namespace evo::world {
|
||||
enum class ChunkError : std::uint8_t {
|
||||
invalid_config,
|
||||
invalid_descriptor,
|
||||
invalid_address,
|
||||
invalid_cells,
|
||||
capacity,
|
||||
memory_budget,
|
||||
missing,
|
||||
stale_view,
|
||||
invalid_local,
|
||||
dirty,
|
||||
revision_exhausted
|
||||
};
|
||||
enum class CellLayout : std::uint8_t { uniform, palette, dense };
|
||||
class ChunkStore;
|
||||
// Immutable owned geometry. Construction does not authorize a terrain edit.
|
||||
class CompactCells {
|
||||
public:
|
||||
// Moves reset the source to a readable uniform void chunk.
|
||||
CompactCells(CompactCells&& other) noexcept;
|
||||
CompactCells& operator=(CompactCells&& other) noexcept;
|
||||
CompactCells(const CompactCells&) = delete;
|
||||
CompactCells& operator=(const CompactCells&) = delete;
|
||||
[[nodiscard]] static std::expected<CompactCells, ChunkError>
|
||||
create(std::span<const CellSample> cells);
|
||||
[[nodiscard]] std::expected<CellSample, ChunkError> read(std::uint32_t index) const noexcept;
|
||||
[[nodiscard]] std::size_t payload_bytes() const noexcept;
|
||||
[[nodiscard]] CellLayout layout() const noexcept {
|
||||
return layout_;
|
||||
}
|
||||
|
||||
private:
|
||||
friend class ChunkStore;
|
||||
CompactCells() = default;
|
||||
static std::size_t required_bytes(std::span<const std::uint32_t> words) noexcept;
|
||||
static CompactCells encode(std::span<const std::uint32_t> words);
|
||||
CellLayout layout_{CellLayout::uniform};
|
||||
std::uint32_t uniform_{};
|
||||
std::uint32_t keys_{};
|
||||
std::unique_ptr<std::uint32_t[]> data_;
|
||||
};
|
||||
// Non-owning token; must not outlive the issuing store. Never exposes storage pointers.
|
||||
class ChunkView {
|
||||
public:
|
||||
[[nodiscard]] std::uint64_t revision() const noexcept {
|
||||
return revision_;
|
||||
}
|
||||
|
||||
private:
|
||||
friend class ChunkStore;
|
||||
ChunkView(const ChunkStore* owner, std::size_t slot, std::uint64_t revision)
|
||||
: owner_{owner}, slot_{slot}, revision_{revision} {}
|
||||
const ChunkStore* owner_;
|
||||
std::size_t slot_;
|
||||
std::uint64_t revision_;
|
||||
};
|
||||
class ChunkStore {
|
||||
public:
|
||||
static constexpr std::size_t max_slots = 4096;
|
||||
static constexpr std::size_t scratch_bytes = (4096 + 256) * sizeof(std::uint32_t);
|
||||
[[nodiscard]] static std::expected<std::unique_ptr<ChunkStore>, ChunkError>
|
||||
create(BaseDescriptor descriptor, std::size_t slots, std::size_t byte_budget);
|
||||
ChunkStore(const ChunkStore&) = delete;
|
||||
ChunkStore& operator=(const ChunkStore&) = delete;
|
||||
ChunkStore(ChunkStore&&) = delete;
|
||||
ChunkStore& operator=(ChunkStore&&) = delete;
|
||||
~ChunkStore();
|
||||
[[nodiscard]] static std::expected<std::size_t, ChunkError>
|
||||
minimum_bytes(std::size_t slots) noexcept;
|
||||
[[nodiscard]] std::expected<ChunkView, ChunkError> load(ChunkAddress address);
|
||||
[[nodiscard]] std::expected<ChunkView, ChunkError> view(ChunkAddress address) const noexcept;
|
||||
[[nodiscard]] std::expected<CellSample, ChunkError> read(ChunkView view,
|
||||
LocalCell local) const noexcept;
|
||||
// Conservative pin only: no geometry edit or durability acknowledgement.
|
||||
[[nodiscard]] std::expected<ChunkView, ChunkError> mark_dirty(ChunkView view) noexcept;
|
||||
[[nodiscard]] std::expected<void, ChunkError> evict(ChunkView view) noexcept;
|
||||
[[nodiscard]] std::size_t accounted_bytes() const noexcept {
|
||||
return bytes_;
|
||||
}
|
||||
[[nodiscard]] std::size_t size() const noexcept {
|
||||
return size_;
|
||||
}
|
||||
|
||||
private:
|
||||
struct Entry;
|
||||
ChunkStore(BaseDescriptor descriptor, std::size_t slots, std::size_t budget, std::size_t bytes);
|
||||
[[nodiscard]] bool current(ChunkView view) const noexcept;
|
||||
BaseDescriptor descriptor_;
|
||||
std::size_t slots_, budget_, bytes_, size_{};
|
||||
std::uint64_t revision_{};
|
||||
std::unique_ptr<Entry[]> entries_;
|
||||
};
|
||||
} // namespace evo::world
|
||||
@@ -0,0 +1,233 @@
|
||||
#include "evo/world/chunks.hpp"
|
||||
#include <algorithm>
|
||||
#include <array>
|
||||
#include <limits>
|
||||
#include <optional>
|
||||
#include <utility>
|
||||
|
||||
namespace evo::world {
|
||||
namespace {
|
||||
std::uint32_t pack(CellSample cell) noexcept {
|
||||
return cell.material().value | (static_cast<std::uint32_t>(cell.fill()) << 16U);
|
||||
}
|
||||
// 257 signals dense fallback. Caller always supplies exactly 4096 valid words.
|
||||
std::uint32_t collect(std::span<const std::uint32_t> words,
|
||||
std::array<std::uint32_t, 256>& keys) noexcept {
|
||||
std::uint32_t count = 0;
|
||||
for (const auto word : words) {
|
||||
const auto end = keys.begin() + count;
|
||||
if (std::find(keys.begin(), end, word) == end) {
|
||||
if (count == 256) {
|
||||
return 257;
|
||||
}
|
||||
keys[count++] = word;
|
||||
}
|
||||
}
|
||||
return count;
|
||||
}
|
||||
} // namespace
|
||||
CompactCells::CompactCells(CompactCells&& other) noexcept {
|
||||
*this = std::move(other);
|
||||
}
|
||||
CompactCells& CompactCells::operator=(CompactCells&& other) noexcept {
|
||||
if (this != &other) {
|
||||
layout_ = std::exchange(other.layout_, CellLayout::uniform);
|
||||
uniform_ = std::exchange(other.uniform_, 0);
|
||||
keys_ = std::exchange(other.keys_, 0);
|
||||
data_ = std::move(other.data_);
|
||||
}
|
||||
return *this;
|
||||
}
|
||||
std::size_t CompactCells::required_bytes(std::span<const std::uint32_t> words) noexcept {
|
||||
std::array<std::uint32_t, 256> keys{};
|
||||
const auto count = collect(words, keys);
|
||||
if (count == 1) {
|
||||
return 0;
|
||||
}
|
||||
return (count > 256 ? 4096 : 1024 + static_cast<std::size_t>(count)) * sizeof(std::uint32_t);
|
||||
}
|
||||
CompactCells CompactCells::encode(std::span<const std::uint32_t> words) {
|
||||
std::array<std::uint32_t, 256> keys{};
|
||||
const auto count = collect(words, keys);
|
||||
CompactCells result;
|
||||
if (count == 1) {
|
||||
result.uniform_ = keys[0];
|
||||
} else if (count > 256) {
|
||||
result.layout_ = CellLayout::dense;
|
||||
result.data_ = std::make_unique<std::uint32_t[]>(4096);
|
||||
std::copy(words.begin(), words.end(), result.data_.get());
|
||||
} else {
|
||||
result.layout_ = CellLayout::palette;
|
||||
result.keys_ = count;
|
||||
result.data_ = std::make_unique<std::uint32_t[]>(1024 + static_cast<std::size_t>(count));
|
||||
std::copy_n(keys.begin(), count, result.data_.get());
|
||||
for (std::size_t i = 0; i < words.size(); ++i) {
|
||||
const auto key = static_cast<std::uint32_t>(
|
||||
std::find(keys.begin(), keys.begin() + count, words[i]) - keys.begin());
|
||||
result.data_[count + i / 4] |= key << ((i % 4) * 8);
|
||||
}
|
||||
}
|
||||
return result;
|
||||
}
|
||||
std::expected<CompactCells, ChunkError> CompactCells::create(std::span<const CellSample> cells) {
|
||||
if (cells.size() != base_chunk_cells) {
|
||||
return std::unexpected{ChunkError::invalid_cells};
|
||||
}
|
||||
std::array<std::uint32_t, base_chunk_cells> words{};
|
||||
std::transform(cells.begin(), cells.end(), words.begin(), pack);
|
||||
return encode(words);
|
||||
}
|
||||
std::size_t CompactCells::payload_bytes() const noexcept {
|
||||
if (layout_ == CellLayout::uniform) {
|
||||
return 0;
|
||||
}
|
||||
return (layout_ == CellLayout::dense ? 4096 : 1024 + static_cast<std::size_t>(keys_)) *
|
||||
sizeof(std::uint32_t);
|
||||
}
|
||||
std::expected<CellSample, ChunkError> CompactCells::read(std::uint32_t index) const noexcept {
|
||||
if (index >= base_chunk_cells) {
|
||||
return std::unexpected{ChunkError::invalid_local};
|
||||
}
|
||||
auto word = uniform_;
|
||||
if (layout_ == CellLayout::dense) {
|
||||
word = data_[index];
|
||||
}
|
||||
if (layout_ == CellLayout::palette) {
|
||||
const auto key = (data_[keys_ + index / 4] >> ((index % 4) * 8)) & 255U;
|
||||
word = data_[key];
|
||||
}
|
||||
return *CellSample::create({static_cast<std::uint16_t>(word & 65535U)}, word >> 16U);
|
||||
}
|
||||
struct ChunkStore::Entry {
|
||||
ChunkAddress address{};
|
||||
std::optional<CompactCells> cells;
|
||||
std::uint64_t revision{};
|
||||
bool dirty{};
|
||||
};
|
||||
ChunkStore::ChunkStore(BaseDescriptor descriptor, std::size_t slots, std::size_t budget,
|
||||
std::size_t bytes)
|
||||
: descriptor_{descriptor}, slots_{slots}, budget_{budget}, bytes_{bytes},
|
||||
entries_{std::make_unique<Entry[]>(slots)} {}
|
||||
ChunkStore::~ChunkStore() = default;
|
||||
std::expected<std::size_t, ChunkError> ChunkStore::minimum_bytes(std::size_t slots) noexcept {
|
||||
if (slots == 0 || slots > max_slots) {
|
||||
return std::unexpected{ChunkError::invalid_config};
|
||||
}
|
||||
return sizeof(ChunkStore) + slots * sizeof(Entry) + scratch_bytes;
|
||||
}
|
||||
std::expected<std::unique_ptr<ChunkStore>, ChunkError>
|
||||
ChunkStore::create(BaseDescriptor descriptor, std::size_t slots, std::size_t budget) {
|
||||
const auto minimum = minimum_bytes(slots);
|
||||
if (!minimum) {
|
||||
return std::unexpected{minimum.error()};
|
||||
}
|
||||
if (!base_sample(descriptor, {})) {
|
||||
return std::unexpected{ChunkError::invalid_descriptor};
|
||||
}
|
||||
if (budget < *minimum) {
|
||||
return std::unexpected{ChunkError::memory_budget};
|
||||
}
|
||||
return std::unique_ptr<ChunkStore>{new ChunkStore(descriptor, slots, budget, *minimum)};
|
||||
}
|
||||
bool ChunkStore::current(ChunkView v) const noexcept {
|
||||
return v.owner_ == this && v.slot_ < slots_ && entries_[v.slot_].cells &&
|
||||
entries_[v.slot_].revision == v.revision_;
|
||||
}
|
||||
std::expected<ChunkView, ChunkError> ChunkStore::view(ChunkAddress address) const noexcept {
|
||||
if (!join({address, {}}, base_chunk_edge)) {
|
||||
return std::unexpected{ChunkError::invalid_address};
|
||||
}
|
||||
for (std::size_t i = 0; i < slots_; ++i) {
|
||||
if (entries_[i].cells && entries_[i].address == address) {
|
||||
return ChunkView{this, i, entries_[i].revision};
|
||||
}
|
||||
}
|
||||
return std::unexpected{ChunkError::missing};
|
||||
}
|
||||
std::expected<ChunkView, ChunkError> ChunkStore::load(ChunkAddress address) {
|
||||
const auto existing = view(address);
|
||||
if (existing) {
|
||||
return existing;
|
||||
}
|
||||
if (existing.error() != ChunkError::missing) {
|
||||
return std::unexpected{existing.error()};
|
||||
}
|
||||
if (size_ == slots_) {
|
||||
return std::unexpected{ChunkError::capacity};
|
||||
}
|
||||
if (revision_ == std::numeric_limits<std::uint64_t>::max()) {
|
||||
return std::unexpected{ChunkError::revision_exhausted};
|
||||
}
|
||||
std::array<std::uint32_t, base_chunk_cells> words{};
|
||||
const auto origin = *join({address, {}}, base_chunk_edge);
|
||||
for (std::uint32_t i = 0; i < base_chunk_cells; ++i) {
|
||||
const auto local = *local_from_ordinal(i, base_chunk_edge);
|
||||
words[i] = pack(*base_sample(descriptor_,
|
||||
{origin.x + local.x, origin.y + local.y, origin.z + local.z}));
|
||||
}
|
||||
const auto payload = CompactCells::required_bytes(words);
|
||||
if (payload > budget_ - bytes_) {
|
||||
return std::unexpected{ChunkError::memory_budget};
|
||||
}
|
||||
auto cells = CompactCells::encode(words); // All fallible allocation precedes publication.
|
||||
for (std::size_t i = 0; i < slots_; ++i) {
|
||||
auto& entry = entries_[i];
|
||||
if (!entry.cells) {
|
||||
entry.address = address;
|
||||
entry.cells.emplace(std::move(cells));
|
||||
entry.revision = ++revision_;
|
||||
entry.dirty = false;
|
||||
bytes_ += payload;
|
||||
++size_;
|
||||
return ChunkView{this, i, entry.revision};
|
||||
}
|
||||
}
|
||||
return std::unexpected{ChunkError::capacity};
|
||||
}
|
||||
std::expected<CellSample, ChunkError> ChunkStore::read(ChunkView v,
|
||||
LocalCell local) const noexcept {
|
||||
if (!current(v)) {
|
||||
return std::unexpected{ChunkError::stale_view};
|
||||
}
|
||||
const auto i = ordinal(local, base_chunk_edge);
|
||||
if (!i) {
|
||||
return std::unexpected{ChunkError::invalid_local};
|
||||
}
|
||||
const auto& cells = entries_[v.slot_].cells;
|
||||
if (!cells) {
|
||||
return std::unexpected{ChunkError::stale_view};
|
||||
}
|
||||
return cells->read(*i);
|
||||
}
|
||||
std::expected<ChunkView, ChunkError> ChunkStore::mark_dirty(ChunkView v) noexcept {
|
||||
if (!current(v)) {
|
||||
return std::unexpected{ChunkError::stale_view};
|
||||
}
|
||||
auto& entry = entries_[v.slot_];
|
||||
if (entry.dirty) {
|
||||
return v;
|
||||
}
|
||||
if (revision_ == std::numeric_limits<std::uint64_t>::max()) {
|
||||
return std::unexpected{ChunkError::revision_exhausted};
|
||||
}
|
||||
entry.dirty = true;
|
||||
entry.revision = ++revision_;
|
||||
return ChunkView{this, v.slot_, entry.revision};
|
||||
}
|
||||
std::expected<void, ChunkError> ChunkStore::evict(ChunkView v) noexcept {
|
||||
if (!current(v)) {
|
||||
return std::unexpected{ChunkError::stale_view};
|
||||
}
|
||||
auto& entry = entries_[v.slot_];
|
||||
if (entry.dirty) {
|
||||
return std::unexpected{ChunkError::dirty};
|
||||
}
|
||||
if (!entry.cells) {
|
||||
return std::unexpected{ChunkError::stale_view};
|
||||
}
|
||||
bytes_ -= entry.cells->payload_bytes();
|
||||
entry.cells.reset();
|
||||
--size_;
|
||||
return {};
|
||||
}
|
||||
} // namespace evo::world
|
||||
@@ -0,0 +1,181 @@
|
||||
#include "evo/world/chunks.hpp"
|
||||
#include <array>
|
||||
#include <cstdio>
|
||||
#include <limits>
|
||||
#include <source_location>
|
||||
#include <stdexcept>
|
||||
#include <string>
|
||||
#include <utility>
|
||||
#include <vector>
|
||||
|
||||
namespace {
|
||||
using namespace evo::world;
|
||||
void check(bool condition, std::source_location at = std::source_location::current()) {
|
||||
if (!condition) {
|
||||
throw std::runtime_error("world chunk line " + std::to_string(at.line()));
|
||||
}
|
||||
}
|
||||
#define CHECK(...) check(static_cast<bool>(__VA_ARGS__))
|
||||
template <typename T> bool refused(const std::expected<T, ChunkError>& r, ChunkError e) {
|
||||
return !r && r.error() == e;
|
||||
}
|
||||
CellSample cell(std::uint16_t id, std::uint32_t fill) {
|
||||
const auto result = CellSample::create({id}, fill);
|
||||
CHECK(result);
|
||||
return *result;
|
||||
}
|
||||
void compact_layouts() {
|
||||
for (const auto count : {1U, 2U, 255U, 256U, 257U, 4096U}) {
|
||||
std::vector<CellSample> input;
|
||||
input.reserve(4096);
|
||||
for (std::uint32_t i = 0; i < 4096; ++i) {
|
||||
// Same material, distinct fill: palette identity must include both.
|
||||
input.push_back(cell(1, 1 + i % count));
|
||||
}
|
||||
auto compact = CompactCells::create(input);
|
||||
CHECK(compact);
|
||||
CHECK(compact->layout() == (count == 1
|
||||
? CellLayout::uniform
|
||||
: (count > 256 ? CellLayout::dense : CellLayout::palette)));
|
||||
CHECK(compact->payload_bytes() ==
|
||||
(count == 1 ? 0 : (count > 256 ? 16384 : 4096 + 4 * count)));
|
||||
for (std::uint32_t i = 0; i < 4096; ++i) {
|
||||
const auto value = compact->read(i);
|
||||
CHECK(value && *value == input[i]);
|
||||
}
|
||||
CHECK(refused(compact->read(4096), ChunkError::invalid_local));
|
||||
CHECK(refused(compact->read(std::numeric_limits<std::uint32_t>::max()),
|
||||
ChunkError::invalid_local));
|
||||
auto moved = std::move(*compact);
|
||||
CHECK(compact->payload_bytes() == 0 && compact->read(0)->material().value == 0);
|
||||
CHECK(moved.read(4095) && *moved.read(4095) == input[4095]);
|
||||
*compact = std::move(moved);
|
||||
// Explicitly test the documented empty-void moved-from guarantee.
|
||||
// NOLINTNEXTLINE(bugprone-use-after-move)
|
||||
CHECK(moved.payload_bytes() == 0 && moved.read(0)->fill() == 0);
|
||||
CHECK(*compact->read(0) == input[0]);
|
||||
}
|
||||
std::vector<CellSample> empty;
|
||||
CHECK(refused(CompactCells::create(empty), ChunkError::invalid_cells));
|
||||
empty.assign(4097, cell(0, 0));
|
||||
CHECK(refused(CompactCells::create(empty), ChunkError::invalid_cells));
|
||||
empty.resize(4096, cell(0, 0));
|
||||
auto uniform = CompactCells::create(empty);
|
||||
CHECK(uniform && uniform->layout() == CellLayout::uniform && uniform->payload_bytes() == 0);
|
||||
// Distinct material identities must survive, even with identical fill.
|
||||
for (std::uint32_t i = 0; i < 4096; ++i) {
|
||||
empty[i] = cell(static_cast<std::uint16_t>(1 + i % 3), 65535);
|
||||
}
|
||||
const auto materials = CompactCells::create(empty);
|
||||
CHECK(materials && materials->layout() == CellLayout::palette);
|
||||
for (std::uint32_t i = 0; i < 4096; ++i) {
|
||||
CHECK(*materials->read(i) == empty[i]);
|
||||
}
|
||||
}
|
||||
void bounded_store() {
|
||||
const auto minimum = ChunkStore::minimum_bytes(2);
|
||||
CHECK(minimum);
|
||||
auto made = ChunkStore::create({73}, 2, *minimum + 32768);
|
||||
CHECK(made);
|
||||
auto& store = **made;
|
||||
CHECK(store.size() == 0 && store.accounted_bytes() == *minimum);
|
||||
CHECK(refused(store.view({}), ChunkError::missing));
|
||||
const auto a = store.load({-1, 0, -1});
|
||||
CHECK(a);
|
||||
const auto first_bytes = store.accounted_bytes();
|
||||
const auto same = store.load({-1, 0, -1});
|
||||
CHECK(same && same->revision() == a->revision() && store.accounted_bytes() == first_bytes);
|
||||
const auto b = store.load({65535, -65536, 65535});
|
||||
CHECK(b);
|
||||
CHECK(store.size() == 2 && store.accounted_bytes() == first_bytes); // far uniform void
|
||||
CHECK(refused(store.load({7, 8, 9}), ChunkError::capacity));
|
||||
for (std::uint32_t i = 0; i < 4096; ++i) {
|
||||
const auto local = *local_from_ordinal(i, 16);
|
||||
const auto expected =
|
||||
base_sample({73}, {std::int64_t{-16} + local.x, local.y, std::int64_t{-16} + local.z});
|
||||
const auto actual = store.read(*a, local);
|
||||
CHECK(expected && actual && *expected == *actual);
|
||||
}
|
||||
CHECK(refused(store.read(*a, {16, 0, 0}), ChunkError::invalid_local));
|
||||
CHECK(store.evict(*a));
|
||||
CHECK(refused(store.read(*a, {}), ChunkError::stale_view));
|
||||
CHECK(refused(store.evict(*a), ChunkError::stale_view));
|
||||
CHECK(refused(store.mark_dirty(*a), ChunkError::stale_view));
|
||||
const auto reloaded = store.load({-1, 0, -1});
|
||||
CHECK(reloaded);
|
||||
CHECK(reloaded->revision() != a->revision());
|
||||
CHECK(refused(store.read(*a, {}), ChunkError::stale_view));
|
||||
CHECK(store.accounted_bytes() == first_bytes);
|
||||
CHECK(*store.read(*reloaded, {0, 0, 0}) == *base_sample({73}, {-16, 0, -16}));
|
||||
const auto dirty = store.mark_dirty(*reloaded);
|
||||
CHECK(dirty);
|
||||
CHECK(refused(store.read(*reloaded, {}), ChunkError::stale_view));
|
||||
CHECK(refused(store.evict(*dirty), ChunkError::dirty));
|
||||
CHECK(store.read(*dirty, {}));
|
||||
const auto repeated = store.mark_dirty(*dirty);
|
||||
CHECK(repeated && repeated->revision() == dirty->revision());
|
||||
CHECK(store.size() == 2 && store.accounted_bytes() == first_bytes);
|
||||
auto other = ChunkStore::create({73}, 2, *minimum + 32768);
|
||||
CHECK(other);
|
||||
CHECK(refused((*other)->read(*dirty, {}), ChunkError::stale_view));
|
||||
CHECK(refused((*other)->evict(*dirty), ChunkError::stale_view));
|
||||
CHECK(refused((*other)->mark_dirty(*dirty), ChunkError::stale_view));
|
||||
// Dirty state here is only a test pin, no modified geometry is discarded.
|
||||
}
|
||||
void budgets_and_rejection() {
|
||||
using E = ChunkError;
|
||||
CHECK(refused(ChunkStore::minimum_bytes(0), E::invalid_config));
|
||||
CHECK(refused(ChunkStore::minimum_bytes(std::numeric_limits<std::size_t>::max()),
|
||||
E::invalid_config));
|
||||
const auto minimum = *ChunkStore::minimum_bytes(3);
|
||||
CHECK(refused(ChunkStore::create({}, 3, minimum - 1), E::memory_budget));
|
||||
BaseDescriptor invalid{};
|
||||
invalid.generator_version = 2;
|
||||
CHECK(refused(ChunkStore::create(invalid, 3, minimum), E::invalid_descriptor));
|
||||
auto created = ChunkStore::create({}, 3, minimum);
|
||||
CHECK(created);
|
||||
auto& store = **created;
|
||||
const auto uniform = store.load({1000, -1000, 1000});
|
||||
CHECK(uniform);
|
||||
CHECK(store.accounted_bytes() == minimum);
|
||||
CHECK(refused(store.load({0, 0, 0}), E::memory_budget));
|
||||
CHECK(store.size() == 1 && store.accounted_bytes() == minimum && store.read(*uniform, {}));
|
||||
CHECK(refused(store.view({0, 0, 0}), E::missing));
|
||||
const auto base = generate_base_chunk({}, {});
|
||||
CHECK(base);
|
||||
const auto compact = CompactCells::create(*base);
|
||||
CHECK(compact);
|
||||
const auto needed = compact->payload_bytes();
|
||||
CHECK(needed > 0);
|
||||
auto exact = ChunkStore::create({}, 3, minimum + needed);
|
||||
CHECK(exact);
|
||||
const auto at = (*exact)->load({});
|
||||
CHECK(at);
|
||||
CHECK((*exact)->accounted_bytes() == minimum + needed);
|
||||
CHECK(refused((*exact)->load({1, 0, 0}), E::memory_budget));
|
||||
CHECK((*exact)->evict(*at));
|
||||
CHECK((*exact)->accounted_bytes() == minimum);
|
||||
CHECK((*exact)->load({1, 0, 0}));
|
||||
constexpr auto low = std::numeric_limits<std::int64_t>::min();
|
||||
constexpr auto high = std::numeric_limits<std::int64_t>::max();
|
||||
for (const auto bad : std::array<std::int64_t, 4>{low, high, -65537, 65536}) {
|
||||
for (const auto addr :
|
||||
{ChunkAddress{bad, 0, 0}, ChunkAddress{0, bad, 0}, ChunkAddress{0, 0, bad}}) {
|
||||
CHECK(refused(store.load(addr), E::invalid_address));
|
||||
CHECK(refused(store.view(addr), E::invalid_address));
|
||||
}
|
||||
}
|
||||
CHECK(store.size() == 1 && store.accounted_bytes() == minimum);
|
||||
}
|
||||
} // namespace
|
||||
int main() try {
|
||||
compact_layouts();
|
||||
bounded_store();
|
||||
budgets_and_rejection();
|
||||
return 0;
|
||||
} catch (const std::exception& e) {
|
||||
std::fprintf(stderr, "%s\n", e.what());
|
||||
return 1;
|
||||
} catch (...) {
|
||||
return 1;
|
||||
}
|
||||
Reference in New Issue
Block a user