Trait ContextAccess

Source

pub trait ContextAccess {
Show 17 methods    // Required methods
    fn global(&self, idx: u32) -> &Value;
    fn set_global(&mut self, idx: u32, value: Value);
    fn visit_count(&self, id: DefinitionId) -> u32;
    fn increment_visit(&mut self, id: DefinitionId);
    fn set_visit_count(&mut self, id: DefinitionId, count: u32);
    fn turn_count(&self, id: DefinitionId) -> Option<u32>;
    fn set_turn_count(&mut self, id: DefinitionId, turn: u32);
    fn turn_index(&self) -> u32;
    fn increment_turn_index(&mut self);
    fn set_turn_index(&mut self, index: u32);
    fn rng_seed(&self) -> i32;
    fn set_rng_seed(&mut self, seed: i32);
    fn previous_random(&self) -> i32;
    fn set_previous_random(&mut self, val: i32);
    fn next_random<R: StoryRng>(&self, seed: i32) -> i32;
    fn random_sequence<R: StoryRng>(&self, seed: i32, count: usize) -> Vec<i32>;

    // Provided method
    fn take_global(&mut self, idx: u32) -> Value { ... }
}

Expand description

Trait for accessing and mutating story execution state.

This is the interface between the VM and the mutable story state. World implements it directly, as does the ContextView routing view. ObservedContext wraps an implementor and fires WriteObserver callbacks on mutations. Consumers can also implement this trait themselves to plug in custom observers (e.g. bevy events) or alternate storage backends.

This does NOT include Program, resolver, or any immutable data — it’s purely the mutable state surface.

Required Methods§

Source

fn set_visit_count(&mut self, id: DefinitionId, count: u32)

Set a visit count directly, rather than incrementing it. Used by crate::load_state to reconcile a durable save, whose entries carry absolute counts rather than deltas.

Source

fn turn_count(&self, id: DefinitionId) -> Option<u32>

Source

fn set_turn_count(&mut self, id: DefinitionId, turn: u32)

Source

fn turn_index(&self) -> u32

Source

fn increment_turn_index(&mut self)

Source

fn set_turn_index(&mut self, index: u32)

Set the turn index directly, rather than incrementing it. Used by crate::load_state to restore a saved turn index.

Source

fn rng_seed(&self) -> i32

Source

fn set_rng_seed(&mut self, seed: i32)

Source

fn previous_random(&self) -> i32

Source

fn set_previous_random(&mut self, val: i32)

Source

fn next_random<R: StoryRng>(&self, seed: i32) -> i32

Source

fn random_sequence<R: StoryRng>(&self, seed: i32, count: usize) -> Vec<i32>

Provided Methods§

Source

fn take_global(&mut self, idx: u32) -> Value

Move a global’s current value out, leaving Value::Null behind — the take-half of the take → make_mut → write-back RMW discipline (docs/value-model-spec.md §5) that closes the indexed-write COW cliff: reading a collection via global clones its Arc (bumping the refcount array_make_mut/map_make_mut checks), so a subsequent in-place mutation always sees itself as “shared” and COW-copies. Taking instead of cloning means a slot that’s the sole owner of its value stays the sole owner all the way to the mutate site, so the mutation completes in place — O(1) amortized instead of O(n) per write in a loop.

Default implementation: clone + null out — always correct (identical observable result to GetGlobal followed by SetGlobal(Null)), just not free of the extra Arc clone. World, whose globals are a flat Vec<Value>, overrides this with a real core::mem::replace move. ContextView delegates to World::take_global for World-scoped units (the common case every oracle-corpus program exercises) and falls back to this default for Local-scoped units, whose per-flow override map can’t move out of an immutable frozen-base ancestor.