Implement M5.4 bounded compact chunk ownership

This commit is contained in:
dingo
2026-09-26 14:34:22 -04:00
parent e2f99b780f
commit 25ac646f93
12 changed files with 729 additions and 4 deletions
+7 -1
View File
@@ -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)
+1
View File
@@ -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
View File
@@ -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
View File
@@ -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.
+63
View File
@@ -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.
+2
View File
@@ -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.
+8
View File
@@ -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.
+31
View File
@@ -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.
+89
View File
@@ -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.
+102
View File
@@ -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
+233
View File
@@ -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
+181
View File
@@ -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;
}