208 lines
6.6 KiB
Markdown
208 lines
6.6 KiB
Markdown
# Events and Scheduling
|
|
|
|
Domain: machine events and frame scheduling
|
|
Function: normative
|
|
|
|
This chapter defines events, timers, faults, and the frame-boundary model of the PROMETEU machine.
|
|
|
|
Coroutine lifecycle and cooperative scheduling details now live in a dedicated companion chapter.
|
|
|
|
## 1 Core Philosophy
|
|
|
|
PROMETEU does not model hidden asynchronous execution.
|
|
|
|
Machine-visible event behavior is based on:
|
|
|
|
- explicit frame steps;
|
|
- deterministic delivery points;
|
|
- observable costs;
|
|
- no surprise callbacks.
|
|
|
|
## 2 Events
|
|
|
|
### 2.1 Definition
|
|
|
|
Events are machine-level facts made visible to the system in controlled phases.
|
|
|
|
Examples include:
|
|
|
|
- input state changes;
|
|
- timer expiry;
|
|
- host-signaled machine events;
|
|
- fault publication at the machine boundary.
|
|
|
|
### 2.2 Event Queue
|
|
|
|
Events are conceptually queued and processed at known synchronization points.
|
|
|
|
The machine model forbids arbitrary guest code execution at event arrival time.
|
|
|
|
## 3 Frame Boundary (Sync Phase)
|
|
|
|
The frame boundary is the primary global synchronization point of the machine.
|
|
|
|
At this phase, the system may:
|
|
|
|
- sample input;
|
|
- deliver pending events;
|
|
- account for frame-level work;
|
|
- coordinate VM/runtime/firmware transitions around `FRAME_SYNC`.
|
|
|
|
This preserves determinism and keeps machine behavior legible.
|
|
|
|
## 4 System Events vs System Faults
|
|
|
|
### 4.1 Normal events
|
|
|
|
Normal events report machine state changes without implying system failure.
|
|
|
|
### 4.2 System faults
|
|
|
|
System faults are not ordinary events.
|
|
|
|
When a terminal fault occurs:
|
|
|
|
- execution stops or transitions to fault-handling flow;
|
|
- diagnostics are produced;
|
|
- the fault is not treated like a recoverable guest event queue item.
|
|
|
|
## 5 Timers
|
|
|
|
Timers are modeled as frame-based counters.
|
|
|
|
Properties:
|
|
|
|
- measured in frames, not wall-clock time;
|
|
- deterministic across runs;
|
|
- integrated with the frame model rather than hidden interrupts.
|
|
|
|
Timers do not execute code by themselves; they make state or events available to be observed at deterministic boundaries.
|
|
|
|
## 6 Relationship Between Events and the Frame Loop
|
|
|
|
High-level structure:
|
|
|
|
```
|
|
FRAME N
|
|
------------------------
|
|
Sample Input
|
|
Deliver Events
|
|
Run VM until:
|
|
- budget exhausted, or
|
|
- FRAME_SYNC reached
|
|
Sync Phase
|
|
------------------------
|
|
```
|
|
|
|
Important properties:
|
|
|
|
- events are processed at known points;
|
|
- no execution occurs outside the frame loop;
|
|
- frame structure remains observable for host tooling and host-owned certification.
|
|
|
|
## 7 Foreground Lifecycle Events
|
|
|
|
Foreground lifecycle events are system events with bounded delivery points.
|
|
They do not execute arbitrary guest callbacks at arrival time.
|
|
|
|
The Game pause path is:
|
|
|
|
```text
|
|
Home/SystemOS request
|
|
-> pause event becomes visible to the Game
|
|
-> bounded pause reaction budget
|
|
-> SystemOS suspension, even if the Game did not cooperate
|
|
```
|
|
|
|
The Game resume path is:
|
|
|
|
```text
|
|
SystemOS resume request
|
|
-> VM reactivation
|
|
-> resume or foreground-restore event becomes visible to the Game
|
|
-> Game may synchronize while still internally paused
|
|
-> visual foreground returns after a valid current-epoch render submission
|
|
```
|
|
|
|
`Paused` is the Game-visible event/state. `Suspended` is the OS-owned
|
|
scheduler/runtime state. A Game may observe pause/resume, but it must not
|
|
control whether SystemOS suspends or resumes the VM.
|
|
|
|
Pause budgets are measured in deterministic machine units, not host wall-clock
|
|
time. A suspended Game receives no normal gameplay ticks, no normal Game input,
|
|
and no frame pacing. Real background execution is outside the v1 foreground
|
|
contract.
|
|
|
|
## 8 Render Worker Concurrency
|
|
|
|
The render worker is not a machine-visible event source and does not introduce
|
|
guest callbacks. It is an implementation-side consumer of closed render
|
|
submissions.
|
|
|
|
The render worker handoff uses single-slot latest-wins semantics:
|
|
|
|
- a producer publishes at most one pending owned `RenderSubmission`;
|
|
- a newer submission replaces an older unconsumed pending submission;
|
|
- replacement is counted as telemetry;
|
|
- the producer does not wait for worker rasterization or host present;
|
|
- the worker takes ownership of the submission it consumes.
|
|
|
|
The worker publishes `OwnedRgba8888Frame` values. Each published frame owns its
|
|
RGBA8888 pixel vector and carries frame and ownership metadata. Repeating a
|
|
frame reuses the latest published owned frame and does not execute guest code
|
|
or recompose the frame.
|
|
|
|
Render resources reachable from a submission are resolved through read-only
|
|
ID-based access. The worker MUST NOT hold mutable VM state, mutable `Hardware`,
|
|
mutable `Gfx`, or a live mutable `FrameComposer` as its cross-thread contract.
|
|
|
|
Shutdown is explicit and bounded. A shutdown request wakes a waiting worker,
|
|
causes pending work that will not be consumed to be discarded, and reports a
|
|
typed failure if the worker cannot join within the configured timeout.
|
|
|
|
## 9 Async Asset and IO Work Lane
|
|
|
|
The asset/IO async work lane is not a machine-visible event source and does not
|
|
introduce guest callbacks. It is an implementation-side lane for asset
|
|
IO/decode/materialization and compatible persistence IO work.
|
|
|
|
The lane is serial:
|
|
|
|
- it has at most one active job;
|
|
- it keeps an ordered backlog;
|
|
- it is separate from the render worker;
|
|
- it must not create one OS thread per guest-visible asset request.
|
|
|
|
Asset jobs are keyed by target `bank_type/slot`. A newer request for the same
|
|
target supersedes the older request. Superseding is an operational status and
|
|
does not execute guest code.
|
|
|
|
Asset install/commit into resident banks happens on the main runtime lane at
|
|
predictable ownership points. The async lane prepares materialized results; it
|
|
does not publish resident graphics/audio/scene state directly.
|
|
|
|
FS and game persistence services may consume this lane for IO-style work, but
|
|
public FS API shape is defined by the FS/app-home contract, not by this chapter.
|
|
|
|
## 10 Determinism and Best Practices
|
|
|
|
PROMETEU encourages:
|
|
|
|
- treating events as data;
|
|
- querying state explicitly;
|
|
- structuring logic around frame boundaries;
|
|
- avoiding implicit control flow hidden behind event delivery.
|
|
|
|
PROMETEU discourages:
|
|
|
|
- asynchronous callback simulation;
|
|
- hidden timing channels;
|
|
- ambiguous out-of-band execution.
|
|
|
|
## 11 Relationship to Other Specs
|
|
|
|
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) defines coroutine lifecycle and scheduling behavior.
|
|
- [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) defines observability and diagnostics surfaces.
|
|
- [`12-firmware-pos-and-prometeuhub.md`](12-firmware-pos-and-prometeuhub.md) defines firmware orchestration at machine level.
|
|
- [`02-vm-instruction-set.md`](02-vm-instruction-set.md) defines VM execution inside this frame model.
|