prometeu-runtime/docs/runtime/specs/09a-coroutines-and-cooperative-scheduling.md

Coroutines and Cooperative Scheduling

Domain: VM coroutine model Function: normative

This chapter isolates PROMETEU coroutine semantics from the broader event/frame model.

1 Coroutine Model

PROMETEU provides coroutines as the only guest-visible concurrency model.

Coroutines are:

• cooperative;
• deterministic;
• scheduled only at safepoints;
• never preemptive.

There is:

• no parallel execution;
• no hidden threads;
• no scheduler behavior outside explicit machine rules.

2 Coroutine Lifecycle

Each coroutine can be in one of the following states:

• Ready
• Running
• Sleeping
• Finished

Coroutine-local execution state includes, conceptually:

Coroutine {
    call_stack
    operand_stack
    state
}

3 Scheduling

At each eligible scheduling boundary:

1. the scheduler selects the next coroutine;
2. ordering remains deterministic;
3. execution continues within the frame-budget model.

Baseline policy:

• round-robin or equivalent deterministic ordering;
• no surprise priority inversion hidden from the model;
• no preemption between safepoints.

4 Coroutine Operations

Typical operations:

Operation	Description
spawn	Create a coroutine
yield	Voluntarily suspend execution
sleep	Suspend for N frames

yield and sleep only take effect at safepoints.

5 Interaction with the Frame Loop

Coroutine scheduling happens inside the frame model, not beside it.

Conceptually:

FRAME N
------------------------
Sample Input
Deliver Events
Schedule Coroutine
Run VM
FRAME_SYNC
------------------------

This preserves:

• deterministic replay;
• explicit cost accounting;
• consistent host/runtime handoff.

6 Costs and Determinism

Coroutine management:

• consumes cycles;
• contributes to certification/cost reporting;
• remains part of the deterministic execution trace.

Nothing about scheduling is "free" or hidden.

7 Relationship to Other Specs

• 09-events-and-concurrency.md defines the broader frame/event model.
• 02-vm-instruction-set.md defines coroutine-related instruction families.
• 03-memory-stack-heap-and-allocation.md defines coroutine-owned execution state in the memory model.