katra-core 0.1.0

//! Deadline classes (Katra3D §15).
//!
//! Work is classified by urgency. The scheduler and prefetcher must never
//! starve required work in favor of speculative work.

use serde::{Deserialize, Serialize};

/// Urgency classification for graph nodes and I/O operations.
#[derive(
    Copy, Clone, Debug, Default, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize,
)]
#[serde(rename_all = "snake_case")]
pub enum DeadlineClass {
    /// Needed for the frame currently being produced.
    #[default]
    ThisFrame,
    /// Needed for the next frame.
    NextFrame,
    /// Blocks a scene transition.
    SceneTransition,
    /// Blocks a loading screen.
    LoadingScreen,
    /// Background streaming; should not block frames.
    BackgroundStreaming,
    /// Speculative prefetch; may be dropped under pressure.
    SpeculativePrefetch,
}

impl DeadlineClass {
    /// All classes in priority order (highest first).
    pub const ALL: [DeadlineClass; 6] = [
        DeadlineClass::ThisFrame,
        DeadlineClass::NextFrame,
        DeadlineClass::SceneTransition,
        DeadlineClass::LoadingScreen,
        DeadlineClass::BackgroundStreaming,
        DeadlineClass::SpeculativePrefetch,
    ];

    /// Numeric priority; lower runs first. 0 = most urgent.
    pub const fn priority(self) -> u8 {
        match self {
            DeadlineClass::ThisFrame => 0,
            DeadlineClass::NextFrame => 1,
            DeadlineClass::SceneTransition => 2,
            DeadlineClass::LoadingScreen => 3,
            DeadlineClass::BackgroundStreaming => 4,
            DeadlineClass::SpeculativePrefetch => 5,
        }
    }

    /// Stable string name.
    pub const fn as_str(self) -> &'static str {
        match self {
            DeadlineClass::ThisFrame => "this_frame",
            DeadlineClass::NextFrame => "next_frame",
            DeadlineClass::SceneTransition => "scene_transition",
            DeadlineClass::LoadingScreen => "loading_screen",
            DeadlineClass::BackgroundStreaming => "background_streaming",
            DeadlineClass::SpeculativePrefetch => "speculative_prefetch",
        }
    }
}

impl std::fmt::Display for DeadlineClass {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}