implements PLN-0123 async work lane specs
This commit is contained in:
@@ -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`
|
||||
|
||||
Reference in New Issue
Block a user