Context

pyrung.core.context

ScanContext - Batched write context for a single scan cycle.

Optimizes performance by batching all tag/memory updates within a scan, reducing object allocation from O(instructions) to O(1) per scan while preserving read-after-write visibility.

ScanContext

Batched write context for a single scan cycle.

Collects all tag and memory writes during a scan cycle, then commits them all at once to produce a new SystemState. Provides read-after-write visibility so subsequent instructions in the same scan see updated values.

Attributes:

Name	Type	Description
_state		The original SystemState (immutable, not modified).
_tags_evolver		Pyrsistent evolver for final tag commit.
_memory_evolver		Pyrsistent evolver for final memory commit.
_tags_pending	dict[str, Any]	Fast lookup dict for pending tag writes.
_memory_pending	dict[str, Any]	Fast lookup dict for pending memory writes.

scan_id property

scan_id: int

Current scan ID from the original state.

timestamp property

timestamp: float

Current timestamp from the original state.

original_state property

original_state: SystemState

Access to the original (unmodified) state.

Useful for operations that need to read original values, such as computing _prev:* for edge detection.

get_tag

get_tag(name: str, default: Any = None) -> Any

Get a tag value, checking pending writes first.

Provides read-after-write visibility within the same scan cycle.

Parameters:

Name	Type	Description	Default
name	str	The tag name to retrieve.	required
default	Any	Value to return if tag not found.	None

Returns:

Type	Description
Any	The tag value from pending writes, original state, or default.

get_memory

get_memory(key: str, default: Any = None) -> Any

Get a memory value, checking pending writes first.

Provides read-after-write visibility within the same scan cycle.

Parameters:

Name	Type	Description	Default
key	str	The memory key to retrieve.	required
default	Any	Value to return if key not found.	None

Returns:

Type	Description
Any	The memory value from pending writes, original state, or default.

set_tag

set_tag(name: str, value: Any) -> None

Set a tag value (batched, committed at end of scan).

Parameters:

Name	Type	Description	Default
name	str	The tag name to set.	required
value	Any	The value to set.	required

set_tags

set_tags(updates: dict[str, Any]) -> None

Set multiple tag values (batched, committed at end of scan).

Parameters:

Name	Type	Description	Default
updates	dict[str, Any]	Dict of tag names to values.	required

set_memory

set_memory(key: str, value: Any) -> None

Set a memory value (batched, committed at end of scan).

Parameters:

Name	Type	Description	Default
key	str	The memory key to set.	required
value	Any	The value to set.	required

set_memory_bulk

set_memory_bulk(updates: dict[str, Any]) -> None

Set multiple memory values (batched, committed at end of scan).

Parameters:

Name	Type	Description	Default
updates	dict[str, Any]	Dict of memory keys to values.	required

commit

commit(dt: float) -> SystemState

Commit all pending changes and advance to next scan.

Creates a new SystemState with all batched tag and memory updates, then advances scan_id and timestamp.

Parameters:

Name	Type	Description	Default
dt	float	Time delta in seconds to add to timestamp.	required

Returns:

Type	Description
SystemState	New SystemState with all changes applied.