implements PLN-0126 asset backlog public api

This commit is contained in:
2026-06-28 14:08:30 +01:00
parent 30c24a4ea7
commit 961557583b
11 changed files with 604 additions and 13 deletions
+325 -9
View File
@@ -2,11 +2,11 @@
use crate::memory_banks::{GlyphBankPoolInstaller, SceneBankPoolInstaller, SoundBankPoolInstaller};
use prometeu_hal::AssetBridge;
use prometeu_hal::asset::{
AssetCodec, AssetEntry, AssetId, AssetLoadError, AssetOpStatus, BankTelemetry, BankType,
HandleId, LoadStatus, PreloadEntry, SCENE_DECODED_LAYER_OVERHEAD_BYTES_V1,
SCENE_HEADER_BYTES_V1, SCENE_LAYER_COUNT_V1, SCENE_LAYER_HEADER_BYTES_V1,
SCENE_PAYLOAD_MAGIC_V1, SCENE_PAYLOAD_VERSION_V1, SCENE_TILE_RECORD_BYTES_V1, SlotRef,
SlotStats,
AssetBacklogInfo, AssetBacklogPosition, AssetCodec, AssetEntry, AssetId, AssetLoadError,
AssetOpStatus, AssetTargetStatus, BankTelemetry, BankType, HandleId, LoadStatus, PreloadEntry,
SCENE_DECODED_LAYER_OVERHEAD_BYTES_V1, SCENE_HEADER_BYTES_V1, SCENE_LAYER_COUNT_V1,
SCENE_LAYER_HEADER_BYTES_V1, SCENE_PAYLOAD_MAGIC_V1, SCENE_PAYLOAD_VERSION_V1,
SCENE_TILE_RECORD_BYTES_V1, SlotRef, SlotStats,
};
use prometeu_hal::cartridge::AssetsPayloadSource;
use prometeu_hal::color::Color;
@@ -220,6 +220,7 @@ struct LoadHandleInfo {
request_generation: u64,
}
#[derive(Clone)]
struct AssetLoadJob {
handle_id: HandleId,
asset_id: AssetId,
@@ -231,6 +232,7 @@ struct AssetLoadJob {
#[derive(Default)]
struct AssetLoadQueueState {
pending: VecDeque<AssetLoadJob>,
active: Option<AssetLoadJob>,
shutdown: bool,
}
@@ -246,6 +248,7 @@ impl AssetLoadQueue {
if state.shutdown {
return;
}
state.pending.retain(|pending| pending.slot != job.slot);
state.pending.push_back(job);
self.ready.notify_one();
}
@@ -254,6 +257,7 @@ impl AssetLoadQueue {
let mut state = self.state.lock().unwrap();
loop {
if let Some(job) = state.pending.pop_front() {
state.active = Some(job.clone());
return Some(job);
}
if state.shutdown {
@@ -267,6 +271,51 @@ impl AssetLoadQueue {
self.state.lock().unwrap().pending.clear();
}
fn complete_active(&self, handle_id: HandleId, request_generation: u64) {
let mut state = self.state.lock().unwrap();
if state.active.as_ref().is_some_and(|job| {
job.handle_id == handle_id && job.request_generation == request_generation
}) {
state.active = None;
}
}
fn pending_count(&self) -> usize {
self.state.lock().unwrap().pending.len()
}
fn active_job(&self) -> Option<AssetLoadJob> {
self.state.lock().unwrap().active.clone()
}
fn pending_position(&self, handle_id: HandleId) -> Option<usize> {
self.state
.lock()
.unwrap()
.pending
.iter()
.position(|job| job.handle_id == handle_id)
.map(|index| index + 1)
}
fn move_pending(&self, handle_id: HandleId, new_position: usize) -> bool {
if new_position == 0 {
return false;
}
let mut state = self.state.lock().unwrap();
let Some(current_index) = state.pending.iter().position(|job| job.handle_id == handle_id)
else {
return false;
};
let Some(job) = state.pending.remove(current_index) else {
return false;
};
let insert_index = new_position.saturating_sub(1).min(state.pending.len());
state.pending.insert(insert_index, job);
true
}
fn shutdown(&self) {
let mut state = self.state.lock().unwrap();
state.pending.clear();
@@ -294,7 +343,7 @@ impl AssetLoadWorker {
let join_handle = thread::spawn(move || {
while let Some(job) = worker_queue.next_job() {
AssetManager::process_load_job(
job,
job.clone(),
&handles,
&target_generations,
&assets_data,
@@ -302,6 +351,7 @@ impl AssetLoadWorker {
&sound_policy,
&scene_policy,
);
worker_queue.complete_active(job.handle_id, job.request_generation);
}
});
@@ -315,6 +365,22 @@ impl AssetLoadWorker {
fn clear_pending(&self) {
self.queue.clear_pending();
}
fn pending_count(&self) -> usize {
self.queue.pending_count()
}
fn active_job(&self) -> Option<AssetLoadJob> {
self.queue.active_job()
}
fn pending_position(&self, handle_id: HandleId) -> Option<usize> {
self.queue.pending_position(handle_id)
}
fn move_pending(&self, handle_id: HandleId, new_position: usize) -> bool {
self.queue.move_pending(handle_id, new_position)
}
}
impl Drop for AssetLoadWorker {
@@ -353,6 +419,24 @@ impl AssetBridge for AssetManager {
fn cancel(&self, handle: HandleId) -> AssetOpStatus {
self.cancel(handle)
}
fn backlog_info(&self) -> AssetBacklogInfo {
self.backlog_info()
}
fn backlog_position(&self, handle: HandleId) -> AssetBacklogPosition {
self.backlog_position(handle)
}
fn backlog_move(&self, handle: HandleId, new_position: usize) -> AssetOpStatus {
self.backlog_move(handle, new_position)
}
fn backlog_promote(&self, handle: HandleId) -> AssetOpStatus {
self.backlog_promote(handle)
}
fn backlog_demote(&self, handle: HandleId) -> AssetOpStatus {
self.backlog_demote(handle)
}
fn target_status(&self, bank_type: BankType, slot: usize) -> AssetTargetStatus {
self.target_status(bank_type, slot)
}
fn apply_commits(&self) {
self.apply_commits()
}
@@ -611,6 +695,26 @@ impl AssetManager {
self.scene_policy.take_staging(handle_id);
}
fn target_for_handle(&self, handle_id: HandleId) -> Option<SlotRef> {
self.target_handles
.read()
.unwrap()
.iter()
.find_map(|(slot, target_handle)| (*target_handle == handle_id).then_some(*slot))
}
fn slot_asset_id(&self, slot: SlotRef) -> Option<AssetId> {
match slot.asset_type {
BankType::GLYPH => self.gfx_slots.read().unwrap().get(slot.index).and_then(|s| *s),
BankType::SOUNDS => self.sound_slots.read().unwrap().get(slot.index).and_then(|s| *s),
BankType::SCENE => self.scene_slots.read().unwrap().get(slot.index).and_then(|s| *s),
}
}
fn idle_target_state(&self, slot: SlotRef) -> LoadStatus {
if self.slot_asset_id(slot).is_some() { LoadStatus::COMMITTED } else { LoadStatus::EMPTY }
}
pub fn load(&self, asset_id: AssetId, slot_index: usize) -> Result<HandleId, AssetLoadError> {
if slot_index >= 16 {
return Err(AssetLoadError::SlotIndexInvalid);
@@ -1176,12 +1280,131 @@ impl AssetManager {
}
pub fn status(&self, handle: HandleId) -> LoadStatus {
self.handles
if let Some(status) = self.handles.read().unwrap().get(&handle).map(|h| h.status) {
return status;
}
self.target_for_handle(handle)
.map(|slot| self.idle_target_state(slot))
.unwrap_or(LoadStatus::UnknownHandle)
}
pub fn backlog_info(&self) -> AssetBacklogInfo {
let active = self.load_worker.active_job();
AssetBacklogInfo {
status: AssetOpStatus::Ok,
pending_count: self.load_worker.pending_count() as u32,
active_handle: active.as_ref().map(|job| job.handle_id).unwrap_or(0),
active_asset_id: active.as_ref().map(|job| job.asset_id),
active_bank_type: active.as_ref().map(|job| job.slot.asset_type),
active_slot: active.as_ref().map(|job| job.slot.index),
active_progress: 0,
}
}
pub fn backlog_position(&self, handle: HandleId) -> AssetBacklogPosition {
let Some(slot) = self.target_for_handle(handle) else {
return AssetBacklogPosition {
status: AssetOpStatus::UnknownHandle,
state: LoadStatus::UnknownHandle,
position: 0,
progress: 0,
};
};
if let Some(position) = self.load_worker.pending_position(handle) {
return AssetBacklogPosition {
status: AssetOpStatus::Ok,
state: LoadStatus::QUEUED,
position: position as u32,
progress: 0,
};
}
if self.load_worker.active_job().as_ref().is_some_and(|job| job.handle_id == handle) {
return AssetBacklogPosition {
status: AssetOpStatus::Ok,
state: LoadStatus::ACTIVE,
position: 0,
progress: 0,
};
}
AssetBacklogPosition {
status: AssetOpStatus::Ok,
state: self
.handles
.read()
.unwrap()
.get(&handle)
.map(|h| h.status)
.unwrap_or_else(|| self.idle_target_state(slot)),
position: 0,
progress: 0,
}
}
pub fn backlog_move(&self, handle: HandleId, new_position: usize) -> AssetOpStatus {
if self.target_for_handle(handle).is_none() {
return AssetOpStatus::UnknownHandle;
}
if self.load_worker.move_pending(handle, new_position) {
AssetOpStatus::Ok
} else {
AssetOpStatus::InvalidState
}
}
pub fn backlog_promote(&self, handle: HandleId) -> AssetOpStatus {
self.backlog_move(handle, 1)
}
pub fn backlog_demote(&self, handle: HandleId) -> AssetOpStatus {
if self.target_for_handle(handle).is_none() {
return AssetOpStatus::UnknownHandle;
}
let new_position = self.load_worker.pending_count();
if new_position == 0 {
return AssetOpStatus::InvalidState;
}
self.backlog_move(handle, new_position)
}
pub fn target_status(&self, bank_type: BankType, slot: usize) -> AssetTargetStatus {
if slot >= 16 {
return AssetTargetStatus {
status: AssetOpStatus::InvalidState,
asset_id: None,
handle: 0,
state: LoadStatus::INVALID,
position: 0,
progress: 0,
};
}
let slot_ref = match bank_type {
BankType::GLYPH => SlotRef::gfx(slot),
BankType::SOUNDS => SlotRef::audio(slot),
BankType::SCENE => SlotRef::scene(slot),
};
let handle = self.handle_for_slot(slot_ref);
let position = self.backlog_position(handle);
let asset_id = self
.handles
.read()
.unwrap()
.get(&handle)
.map(|h| h.status)
.unwrap_or(LoadStatus::UnknownHandle)
.map(|h| h._asset_id)
.or_else(|| self.slot_asset_id(slot_ref));
AssetTargetStatus {
status: AssetOpStatus::Ok,
asset_id,
handle,
state: position.state,
position: position.position,
progress: position.progress,
}
}
pub fn commit(&self, handle: HandleId) -> AssetOpStatus {
@@ -1842,6 +2065,99 @@ mod tests {
assert_eq!(slot.asset_id, Some(1));
}
#[test]
fn test_asset_backlog_queue_reorders_pending_requests() {
let queue = AssetLoadQueue::default();
let entry = test_glyph_asset_entry("queued_glyphs", 16, 16);
let job = |handle_id: HandleId, slot: usize| AssetLoadJob {
handle_id,
asset_id: handle_id as AssetId,
slot: SlotRef::gfx(slot),
request_generation: handle_id as u64,
entry: entry.clone(),
};
queue.submit(job(1, 0));
queue.submit(job(2, 1));
queue.submit(job(3, 2));
assert_eq!(queue.pending_position(3), Some(3));
assert!(queue.move_pending(3, 1));
assert_eq!(queue.pending_position(3), Some(1));
assert_eq!(queue.pending_position(1), Some(2));
assert!(queue.move_pending(3, queue.pending_count()));
assert_eq!(queue.pending_position(3), Some(3));
}
#[test]
fn test_asset_target_status_exposes_empty_and_ready_slot_handle() {
let banks = Arc::new(MemoryBanks::new());
let gfx_installer = Arc::clone(&banks) as Arc<dyn GlyphBankPoolInstaller>;
let sound_installer = Arc::clone(&banks) as Arc<dyn SoundBankPoolInstaller>;
let scene_installer = Arc::clone(&banks) as Arc<dyn SceneBankPoolInstaller>;
let data = test_glyph_asset_data();
let asset_entry = test_glyph_asset_entry("test_glyphs", 16, 16);
let am = AssetManager::new(
vec![asset_entry],
AssetsPayloadSource::from_bytes(data),
gfx_installer,
sound_installer,
scene_installer,
);
let empty = am.target_status(BankType::GLYPH, 0);
assert_eq!(empty.status, AssetOpStatus::Ok);
assert_eq!(empty.asset_id, None);
assert_eq!(empty.state, LoadStatus::EMPTY);
assert_ne!(empty.handle, 0);
assert_eq!(am.status(empty.handle), LoadStatus::EMPTY);
let handle = am.load(0, 0).unwrap();
assert_eq!(handle, empty.handle);
let start = Instant::now();
while am.status(handle) != LoadStatus::READY && start.elapsed().as_secs() < 5 {
thread::sleep(std::time::Duration::from_millis(10));
}
let ready = am.target_status(BankType::GLYPH, 0);
assert_eq!(ready.status, AssetOpStatus::Ok);
assert_eq!(ready.asset_id, Some(0));
assert_eq!(ready.handle, handle);
assert_eq!(ready.state, LoadStatus::READY);
}
#[test]
fn test_asset_backlog_reorder_rejects_non_queued_request() {
let banks = Arc::new(MemoryBanks::new());
let gfx_installer = Arc::clone(&banks) as Arc<dyn GlyphBankPoolInstaller>;
let sound_installer = Arc::clone(&banks) as Arc<dyn SoundBankPoolInstaller>;
let scene_installer = Arc::clone(&banks) as Arc<dyn SceneBankPoolInstaller>;
let data = test_glyph_asset_data();
let asset_entry = test_glyph_asset_entry("test_glyphs", 16, 16);
let am = AssetManager::new(
vec![asset_entry],
AssetsPayloadSource::from_bytes(data),
gfx_installer,
sound_installer,
scene_installer,
);
let handle = am.load(0, 0).unwrap();
let start = Instant::now();
while am.status(handle) != LoadStatus::READY && start.elapsed().as_secs() < 5 {
thread::sleep(std::time::Duration::from_millis(10));
}
assert_eq!(am.backlog_promote(handle), AssetOpStatus::InvalidState);
assert_eq!(am.backlog_demote(handle), AssetOpStatus::InvalidState);
assert_eq!(am.backlog_move(999, 1), AssetOpStatus::UnknownHandle);
}
#[test]
fn test_sound_asset_loading() {
let banks = Arc::new(MemoryBanks::new());