feat(runtime): add optional pause and resume lifecycle hooks
Intrepid/Prometeu/Runtime/pipeline/pr-master Build started...
Intrepid/Prometeu/Runtime/pipeline/pr-master Build started...
This commit is contained in:
@@ -13,7 +13,8 @@ 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, can occur in any body and resumes next PC. Host MUST NOT
|
||||
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.
|
||||
|
||||
@@ -34,3 +35,53 @@ and invoke typed Fn callbacks. UI/SDK APIs and future coroutine protocols requir
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user