6.0 KiB
⚡ Events and Scheduling
This chapter defines how the Prometeu Virtual Machine (PVM) handles events, frame synchronization, and cooperative concurrency. It replaces the older interrupt-oriented terminology with a simpler and more accurate model based on frame boundaries, event queues, and coroutines.
The goal is to preserve determinism while still allowing responsive and structured game logic.
1 Core Philosophy
Prometeu does not use asynchronous callbacks or preemptive interrupts for user code.
All external signals are:
- queued by the firmware
- delivered at deterministic points
- processed inside the main execution loop
Nothing executes “out of time”. Nothing interrupts the program in the middle of an instruction. Nothing occurs without a known cost.
This guarantees:
- deterministic behavior
- reproducible runs
- stable frame timing
2 Events
2.1 Definition
An event is a logical signal generated by the system or by internal runtime mechanisms.
Events:
- represent something that has occurred
- do not execute code automatically
- are processed explicitly during the frame
Examples:
- end of frame
- timer expiration
- asset load completion
- system state change
- execution error
2.2 Event Queue
The firmware maintains an event queue.
Properties:
- events are queued in order
- events are processed at frame boundaries
- event processing is deterministic
Events never:
- execute user code automatically
- interrupt instructions
- run outside the main loop
3 Frame Boundary (Sync Phase)
The primary synchronization point in Prometeu is the frame boundary, reached by the FRAME_SYNC instruction.
At this point:
- Input state is sampled.
- Events are delivered.
- Coroutine scheduling occurs.
- Optional garbage collection may run.
- Control returns to the firmware.
This replaces the older notion of a "VBlank interrupt".
The frame boundary:
- has a fixed, measurable cost
- does not execute arbitrary user code
- is fully deterministic
4 System Events vs System Faults
Prometeu distinguishes between normal events and system faults.
4.1 Normal events
Examples:
- timer expired
- asset loaded
- frame boundary
These are delivered through the event queue.
4.2 System faults
Generated by exceptional conditions:
- invalid instruction
- memory violation
- handle misuse
- verifier failure
Result:
- VM execution stops
- state is preserved
- a diagnostic report is generated
System faults are not recoverable events.
5 Timers
Timers are modeled as frame-based counters.
Properties:
- measured in frames, not real time
- deterministic across runs
- generate events when they expire
Timers:
- do not execute code automatically
- produce queryable or queued events
Example:
if timer.expired(t1) {
// handle event
}
6 Coroutines and Cooperative Scheduling
Prometeu provides coroutines as the only form of concurrency.
Coroutines are:
- cooperative
- deterministic
- scheduled only at safe points
There is:
- no preemption
- no parallel execution
- no hidden threads
6.1 Coroutine lifecycle
Each coroutine can be in one of the following states:
ReadyRunningSleepingFinished
6.2 Scheduling
At each frame boundary:
- The scheduler selects the next coroutine.
- Coroutines run in a deterministic order.
- Each coroutine executes within the frame budget.
The default scheduling policy is:
- round-robin
- deterministic
6.3 Coroutine operations
Typical coroutine instructions:
| Operation | Description |
|---|---|
spawn |
Create a coroutine |
yield |
Voluntarily suspend execution |
sleep |
Suspend for N frames |
yield and sleep only take effect at safe points.
7 Relationship Between Events, Coroutines, and the Frame Loop
The high-level frame structure is:
FRAME N
------------------------
Sample Input
Deliver Events
Schedule Coroutines
Run VM until:
- budget exhausted, or
- FRAME_SYNC reached
Sync Phase
------------------------
Important properties:
- events are processed at known points
- coroutine scheduling is deterministic
- no execution occurs outside the frame loop
8 Costs and Budget
All event processing and scheduling:
- consumes cycles
- contributes to the CAP (certification and analysis profile)
- appears in profiling reports
Example:
Frame 18231:
Event processing: 120 cycles
Coroutine scheduling: 40 cycles
Frame sync: 80 cycles
Nothing is free.
9 Determinism and Reproducibility
Prometeu guarantees:
- same sequence of inputs and events → same behavior
- frame-based timers
- deterministic coroutine scheduling
This allows:
- reliable replays
- precise debugging
- fair certification
10 Best Practices
Prometeu encourages:
- treating events as data
- querying events explicitly
- structuring logic around frame steps
- using coroutines for asynchronous flows
Prometeu discourages:
- simulating asynchronous callbacks
- relying on hidden timing
- using events as implicit control flow
11 Conceptual Comparison
| Traditional System | Prometeu |
|---|---|
| Hardware interrupt | Frame boundary event |
| ISR | System sync phase |
| Main loop | VM frame loop |
| Timer interrupt | Frame-based timer event |
| Threads | Coroutines |
Prometeu teaches reactive system concepts without the unpredictability of real interrupts.
12 Summary
- Events inform; they do not execute code.
- The frame boundary is the only global synchronization point.
- System faults stop execution.
- Coroutines provide cooperative concurrency.
- All behavior is deterministic and measurable.