prometeu-runtime/docs/specs/hardware/topics/chapter-9.md

< [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) >