Files
prometeu-runtime/docs/specs/runtime/09a-coroutines-and-cooperative-scheduling.md
T
bquarkz 0af8b2b1fe
Intrepid/Prometeu/Runtime/pipeline/pr-master Build started...
feat(runtime): add optional pause and resume lifecycle hooks
2026-10-13 12:18:18 +01:00

88 lines
5.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Single Execution Context and Frame Continuation
Domain: VM execution lifecycle
Function: normative
VM directly owns one PC, operand stack, call stack and globals. Entry preparation
does not allocate a heap execution object. There are no guest coroutine instances,
ready/sleeping queues, sleeper clock or coroutine scheduling phase.
SPAWN/YIELD/SLEEP are retired; 0x54–0x56 remain reserved. Loading MUST reject them
before execution, including unreachable code. Assembler rejects their mnemonics;
diagnostic decoding can identify retired numbers. No compatibility mode exists.
Other instruction numbers are unchanged.
FRAME_SYNC closes a logical frame and preserves context. It has zero stack effect,
is not a terminator and resumes next PC. It is forbidden while a lifecycle hook
is active, including in its callees. Host MUST NOT
prepare fresh entry solely because sync occurred. Budget exhaustion/breakpoints
preserve the same open frame without draw publication or extra callback budget.
Successful RET of the last root completes entry and leaves rooted results on VM
stack. Recurring host may prepare FunctionId 0 next logical frame, preserving
globals/init guard. Callee RET does not close a frame. Replacement preparation
validates/reserves before releasing owners. HALT/trap/reset/unload retain their
contracts.
Threshold GC opportunities are sync and successful root RET after result rooting.
Preparation, ordinary callee RET and allocation failure add no opportunity. GC
advances no clock/frame, grants no budget and invokes no guest cleanup/callback.
Asset/render workers retain their independent protocols and run no guest code;
no physical-core affinity is implied.
Persistent operations can advance through short steps in normal frame execution
and invoke typed Fn callbacks. UI/SDK APIs and future coroutine protocols require
separate contracts. See [Fn](02b-vm-function-values-and-closures.md),
[events](09-events-and-concurrency.md) and
[memory](03-memory-stack-heap-and-allocation.md).
## Controlled lifecycle calls
SystemOS optionally invokes the Registry's BeforePause and BeforeResume roles.
BeforePause runs after leaving the existing gameplay loop/handoff and before OS
suspension completes. BeforeResume runs after reactivation and before any normal
gameplay instruction. Neither hook is required, takes arguments, returns a
value, or vetoes the transition. Absence preserves the existing transition.
Direct suspension and Shell foreground handoff obey the same ordering; they do
not add a gameplay reaction tick. Home retains its existing one-tick handoff.
A controlled call appends a frame and locals to the same VM stacks. It retains
the previous PC, halted state and stack boundaries; all suspended stack values,
frame environments, globals and heap references remain roots. Existing stack,
call-depth and allocation quotas include retained frames. Reserve before entry
mutation. Ordinary calls inside the hook work normally. On successful outer
return (including a branch to function end), restore the continuation and return
immediately to SystemOS, even if the execution slice has unused cycles. Never
clear the stacks with boot-entry preparation or execute gameplay in that slice.
Global/heap mutations persist. There is at most one lifecycle invocation per
session; duplicate requests do not reenter or renew it, and conflicting pending
transitions reject.
Each invocation receives 1,500,000 virtual cycles total, sliced at no more than
250,000 admitted cycles per host update. This budget is independent of normal
logical frames and never renews between slices or debugger stops. Positive
remaining budget admits a whole instruction and allows its existing overshoot.
A normal completed return succeeds even if that final instruction consumes the
remaining budget; an unfinished invocation at exhaustion fails. There is no
wall-clock deadline. Breakpoints preserve the invocation and remaining budget;
while stopped, no cycles or gameplay frames advance. Instruction stepping uses
the same budget and the session's real service context.
FRAME_SYNC traps before frame/GC/publication effects, including from ordinary
callees. Fatal traps, host errors/panics and total exhaustion fail the session,
block gameplay and report the failing phase through the existing crash path.
There is no retry, rollback of earlier mutations or compensating other hook.
Normal service-result errors remain guest data. HALT closes the task through
the OS termination path; it is not successful hook return.
Hooks use the existing services and capability checks. No automatic save,
flush, disk-completion wait, guest event queue or reason argument is added.
Host-owned in-flight work keeps its ownership until the service/host safely
releases it; lifecycle failure does not simulate cancellation or free borrowed
buffers. Native calls must return promptly: VM fuel only bounds bytecode and
cannot preempt a blocked native/host call. Existing FS read/write and the current
memcard commit backend are synchronous interfaces, so this implementation does
not promise a wall-time bound for them. The new asynchronous memcard backend
must expose bounded submission/polling independently; hooks can then submit an
explicit commit without waiting for disk completion.