implements PLN-0123 async work lane specs
This commit is contained in:
@@ -127,7 +127,31 @@ 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.
|
||||
|
||||
## 8 Determinism and Best Practices
|
||||
## 8 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.
|
||||
|
||||
## 9 Determinism and Best Practices
|
||||
|
||||
PROMETEU encourages:
|
||||
|
||||
@@ -142,7 +166,7 @@ PROMETEU discourages:
|
||||
- hidden timing channels;
|
||||
- ambiguous out-of-band execution.
|
||||
|
||||
## 9 Relationship to Other Specs
|
||||
## 10 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.
|
||||
|
||||
@@ -393,14 +393,129 @@ Fault boundary:
|
||||
|
||||
Rules:
|
||||
|
||||
- `handle` is valid only when `load` status is `OK`;
|
||||
- `handle` is returned when `load` status is `OK`;
|
||||
- `handle` represents a stable bank slot target, not a worker thread;
|
||||
- a known handle remains queryable even when the slot is empty, has no active
|
||||
request, or has a superseded request;
|
||||
- failed `load` returns `handle = 0`;
|
||||
- `commit` and `cancel` must not be silent no-op for unknown/invalid handle state.
|
||||
- `asset.load` resolves the target bank type from `asset_table` using `asset_id`;
|
||||
- public callers must not supply `asset_name` or `bank_type` to `asset.load`;
|
||||
- slot validation and residency/lifecycle rejection remain in `asset` status space and are not delegated to `bank`.
|
||||
|
||||
### 11.2 Minimum status tables
|
||||
### 11.2 Async work lane and backlog
|
||||
|
||||
Asset loading uses the runtime async work lane. This lane is separate from the
|
||||
VM/main lane and separate from the render worker lane.
|
||||
|
||||
The asset async lane is serial:
|
||||
|
||||
- it executes at most one active asset job at a time;
|
||||
- it keeps an ordered backlog of pending requests;
|
||||
- it must not create one OS thread per `asset.load` request.
|
||||
|
||||
Asset requests are keyed by the target `bank_type/slot`.
|
||||
|
||||
Rules:
|
||||
|
||||
- each `bank_type/slot` has at most one current request;
|
||||
- a newer request for the same `bank_type/slot` supersedes the previous request;
|
||||
- if the previous request is queued, it is removed from the backlog;
|
||||
- if the previous request is active, the lane should cancel cooperatively when
|
||||
the current phase supports cheap cancellation;
|
||||
- if active work cannot stop cheaply, it may finish, but the result must be
|
||||
discarded when its generation no longer matches the target request generation;
|
||||
- if the target already contains the requested `asset_id` as a valid resident
|
||||
asset, `asset.load` returns a ready handle without adding a backlog entry.
|
||||
|
||||
The effective backlog size is bounded by the sum of targetable bank slots,
|
||||
because only one current request can exist per `bank_type/slot`. The runtime
|
||||
does not expose a guest-visible `queue_full` status for the normal asset
|
||||
backlog path.
|
||||
|
||||
### 11.3 Handle state
|
||||
|
||||
An asset handle observes one stable bank slot target. Its observable state has
|
||||
two parts:
|
||||
|
||||
```text
|
||||
handle:
|
||||
bank_type
|
||||
slot
|
||||
|
||||
slot_state:
|
||||
loaded_asset_id
|
||||
resident_state
|
||||
slot_generation
|
||||
|
||||
request_state:
|
||||
requested_asset_id
|
||||
request_generation
|
||||
state
|
||||
backlog_position
|
||||
progress
|
||||
```
|
||||
|
||||
`slot_state` describes what is currently resident in the target slot.
|
||||
`request_state` describes the current or most recent request for that target.
|
||||
|
||||
Mutating operations such as commit, cancel, promote, demote, and move must act
|
||||
on the current request generation. They must not accidentally mutate a newer
|
||||
request through an older handle view.
|
||||
|
||||
### 11.4 Backlog inspection and ordering
|
||||
|
||||
The asset backlog surface may expose these status-first operations:
|
||||
|
||||
- `asset.backlog_info() -> (status, pending_count, active_handle, active_asset_id, active_bank_type, active_slot, active_progress)`
|
||||
- `asset.backlog_position(handle) -> (status, state, position, progress)`
|
||||
- `asset.backlog_move(handle, new_position) -> status`
|
||||
- `asset.backlog_promote(handle) -> status`
|
||||
- `asset.backlog_demote(handle) -> status`
|
||||
- `asset.target_status(bank_type, slot) -> (status, asset_id, handle, state, position, progress)`
|
||||
|
||||
`asset.backlog_promote(handle)` is a shortcut for moving a queued request to
|
||||
position `1`, the first pending position after the active job.
|
||||
|
||||
`asset.backlog_demote(handle)` is a shortcut for moving a queued request to the
|
||||
end of the pending backlog.
|
||||
|
||||
### 11.5 Progress and telemetry
|
||||
|
||||
Asset progress uses integer progress, not floating point. The preferred scale is
|
||||
`0..10000`.
|
||||
|
||||
The initial phase model is:
|
||||
|
||||
```text
|
||||
queued -> 0
|
||||
read -> 0..4000
|
||||
decode -> 4000..9000
|
||||
stage -> 9000..10000
|
||||
ready -> 10000
|
||||
```
|
||||
|
||||
If a phase cannot report internal progress, it keeps the previous progress mark
|
||||
and advances at phase completion. The runtime must not invent false precision
|
||||
for non-linear decode phases.
|
||||
|
||||
Minimum telemetry:
|
||||
|
||||
- current backlog depth;
|
||||
- target/request position;
|
||||
- active job progress;
|
||||
- jobs submitted;
|
||||
- jobs completed;
|
||||
- jobs failed;
|
||||
- jobs canceled;
|
||||
- jobs superseded;
|
||||
- job duration;
|
||||
- percentiles by `bank_type`;
|
||||
- lightweight percentiles or small-window samples by `asset_id`.
|
||||
|
||||
Percentiles are updated when a job closes, not inside the inner decode loop.
|
||||
|
||||
### 11.6 Minimum status tables
|
||||
|
||||
`asset.load` request statuses:
|
||||
|
||||
@@ -418,9 +533,16 @@ Rules:
|
||||
- `4` = `CANCELED`
|
||||
- `5` = `ERROR`
|
||||
- `6` = `UNKNOWN_HANDLE`
|
||||
- `7` = `QUEUED`
|
||||
- `8` = `ACTIVE`
|
||||
- `9` = `SUPERSEDED`
|
||||
- `10` = `EMPTY`
|
||||
- `11` = `INVALID`
|
||||
- `12` = `BACKEND_UNAVAILABLE`
|
||||
|
||||
`asset.commit` and `asset.cancel` operation statuses:
|
||||
|
||||
- `0` = `OK`
|
||||
- `1` = `UNKNOWN_HANDLE`
|
||||
- `2` = `INVALID_STATE`
|
||||
- `3` = `SUPERSEDED`
|
||||
|
||||
@@ -203,6 +203,12 @@ Canonical operations in v1 are:
|
||||
- `asset.status(handle) -> status`
|
||||
- `asset.commit(handle) -> status`
|
||||
- `asset.cancel(handle) -> status`
|
||||
- `asset.backlog_info() -> (status, pending_count, active_handle, active_asset_id, active_bank_type, active_slot, active_progress)`
|
||||
- `asset.backlog_position(handle) -> (status, state, position, progress)`
|
||||
- `asset.backlog_move(handle, new_position) -> status`
|
||||
- `asset.backlog_promote(handle) -> status`
|
||||
- `asset.backlog_demote(handle) -> status`
|
||||
- `asset.target_status(bank_type, slot) -> (status, asset_id, handle, state, position, progress)`
|
||||
|
||||
For `asset.load`:
|
||||
|
||||
@@ -210,6 +216,18 @@ For `asset.load`:
|
||||
- `slot` is the target slot index;
|
||||
- bank kind is resolved from `asset_table` by `asset_id`, not supplied by the caller.
|
||||
|
||||
Asset handles represent stable bank slot targets. A handle can be queried even
|
||||
when its slot has no resident asset or active request. Internally the handle
|
||||
state separates resident `slot_state` from current `request_state`.
|
||||
|
||||
The asset backlog is keyed by `bank_type/slot`. New requests for the same target
|
||||
supersede older requests for that target. `superseded` is an operational status,
|
||||
not a structural trap.
|
||||
|
||||
`asset.backlog_promote(handle)` and `asset.backlog_demote(handle)` are
|
||||
convenience operations over backlog movement. They do not introduce a second
|
||||
ordering model.
|
||||
|
||||
### Bank diagnostics surface (`bank`, v1)
|
||||
|
||||
`DEC-0009` narrows the public bank contract:
|
||||
|
||||
@@ -44,6 +44,9 @@ Normal operational success and operational failure conditions should be represen
|
||||
Examples:
|
||||
|
||||
- asset not yet loaded;
|
||||
- asset request queued or active;
|
||||
- asset request superseded by a newer request for the same bank slot;
|
||||
- asset backend unavailable;
|
||||
- audio voice unavailable;
|
||||
- persistent storage full.
|
||||
|
||||
@@ -107,6 +110,11 @@ Game memcard operations (`mem.*`) are status-first and use `fs` capability in v1
|
||||
`mem` remains layered on runtime `fs`; no parallel persistence channel is introduced.
|
||||
Domain surface, status catalog and slot semantics are defined in [`08-save-memory-and-memcard.md`](08-save-memory-and-memcard.md).
|
||||
|
||||
Asset backlog operations are status-first. `queued`, `active`, `ready`,
|
||||
`canceled`, `superseded`, `empty`, `invalid`, decode failure, and backend
|
||||
unavailability are operational results. They must not be reclassified as `Trap`
|
||||
unless the caller violates the structural ABI contract.
|
||||
|
||||
## 3 Interaction with the Garbage Collector
|
||||
|
||||
The VM heap and host-managed memory are separate.
|
||||
|
||||
Reference in New Issue
Block a user