< [Back](chapter-8.md) | [Summary](table-of-contents.md) | [Next](chapter-10.md) > # ⚡ **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: 1. Input state is sampled. 2. Events are delivered. 3. Coroutine scheduling occurs. 4. Optional garbage collection may run. 5. 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: * `Ready` * `Running` * `Sleeping` * `Finished` ### 6.2 Scheduling At each frame boundary: 1. The scheduler selects the next coroutine. 2. Coroutines run in a deterministic order. 3. 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. < [Back](chapter-8.md) | [Summary](table-of-contents.md) | [Next](chapter-10.md) >