nonbinary.computer
OR-1 dataflow CPU sketch
1"""Command and result protocol types for the simulation backend.
2
3Frozen dataclasses for commands sent to and results received from the
4SimulationBackend, supporting queue-based communication across thread boundaries.
5"""
6
7from __future__ import annotations
8
9from dataclasses import dataclass, field
10
11from asm.ir import IRGraph
12from emu.events import SimEvent
13from monitor.snapshot import StateSnapshot
14from tokens import Token
15
16
17@dataclass(frozen=True)
18class LoadCmd:
19 """Load a dfasm program into a fresh simulation environment.
20
21 Attributes:
22 source: dfasm source code as a string
23 """
24
25 source: str
26
27
28@dataclass(frozen=True)
29class StepTickCmd:
30 """Step the simulation by one tick (all events at current simulation time).
31
32 Empty dataclass; no parameters needed.
33 """
34
35 pass
36
37
38@dataclass(frozen=True)
39class StepEventCmd:
40 """Step the simulation by exactly one event.
41
42 Empty dataclass; no parameters needed.
43 """
44
45 pass
46
47
48@dataclass(frozen=True)
49class RunUntilCmd:
50 """Run the simulation continuously until reaching a target simulation time.
51
52 Attributes:
53 until: Target simulation time (float); events are batched per tick
54 """
55
56 until: float
57
58
59@dataclass(frozen=True)
60class InjectCmd:
61 """Inject a token into the simulation without respecting FIFO backpressure.
62
63 Attributes:
64 token: Token to inject into the appropriate element's input store
65 """
66
67 token: Token
68
69
70@dataclass(frozen=True)
71class SendCmd:
72 """Send a token into the simulation via SimPy store.put() (respects backpressure).
73
74 Attributes:
75 token: Token to send to the appropriate element's input store
76 """
77
78 token: Token
79
80
81@dataclass(frozen=True)
82class ResetCmd:
83 """Reset the simulation (tear down current topology).
84
85 Attributes:
86 reload: If True, reload the last program after reset; otherwise leave backend ready for new LoadCmd
87 """
88
89 reload: bool = False
90
91
92@dataclass(frozen=True)
93class StopCmd:
94 """Stop the backend thread gracefully.
95
96 Empty dataclass; no parameters needed.
97 """
98
99 pass
100
101
102# Union type for all command types
103SimCommand = LoadCmd | StepTickCmd | StepEventCmd | RunUntilCmd | InjectCmd | SendCmd | ResetCmd | StopCmd
104
105
106@dataclass(frozen=True)
107class StepResult:
108 """Result of a step or run command.
109
110 Attributes:
111 events: Tuple of SimEvent objects that occurred during the step
112 snapshot: StateSnapshot of the system after the step (None if not available)
113 sim_time: Current simulation time
114 finished: True if simulation has reached terminal state (env.peek() == inf)
115 """
116
117 events: tuple[SimEvent, ...] = ()
118 snapshot: StateSnapshot | None = None
119 sim_time: float = 0.0
120 finished: bool = False
121
122
123@dataclass(frozen=True)
124class GraphLoaded:
125 """Result of successfully loading a dfasm program.
126
127 Attributes:
128 ir_graph: The loaded and processed IRGraph (for graph rendering, etc.)
129 snapshot: Initial StateSnapshot after seed token injection
130 """
131
132 ir_graph: IRGraph
133 snapshot: StateSnapshot
134
135
136@dataclass(frozen=True)
137class ErrorResult:
138 """Result indicating an error during command processing.
139
140 Attributes:
141 message: Human-readable error message
142 errors: Optional list of structured error messages from assembly
143 """
144
145 message: str
146 errors: list[str] = field(default_factory=list)