swactor/crates/engine/src/backend.rs

//! Execution backend SPI.
//!
//! The [`ExecutionBackend`] trait is an implementation seam the engine uses to
//! schedule work and read engine time. It is not the interface applications
//! consume; that is [`crate::EngineHandle`]. A native implementation erases
//! tasks once when they are installed; this representation is not a
//! cross-target requirement (see `ENGINE_SPEC.md`).

use std::pin::Pin;
use std::time::Duration;

use crate::time::EngineInstant;

/// A boxed, sendable future returned by the engine substrate.
pub type BoxTask = Pin<Box<dyn Future<Output = ()> + Send + 'static>>;
/// A boxed, sendable timer future produced by the substrate.
pub type BoxTimer = Pin<Box<dyn Future<Output = ()> + Send + 'static>>;
/// A boxed, sendable one-shot blocking workload.
pub type BoxWork = Box<dyn FnOnce() + Send + 'static>;

/// The substrate-specific execution surface an engine schedules onto.
///
/// Object-safe so the composite [`Engine`](crate::Engine) can store it as
/// `Arc<dyn ExecutionBackend>` without being generic over the backend.
pub trait ExecutionBackend: Send + Sync + 'static {
    /// Schedule `task` to run as cooperative engine work.
    fn spawn(&self, task: BoxTask);
    /// Schedule `work` on a dedicated blocking thread.
    fn spawn_blocking(&self, work: BoxWork);
    /// Produce a future that completes after `delay`.
    fn timer(&self, delay: Duration) -> BoxTimer;
    /// Read the engine's monotonic clock.
    fn now(&self) -> EngineInstant;
    /// Report the substrate's advertised capabilities.
    fn capabilities(&self) -> Capabilities;
}

/// Capabilities an execution backend advertises.
///
/// - `tasks`: cooperative task scheduling.
/// - `timers`: timer and interval support.
/// - `blocking`: dedicated blocking-thread pools.
/// - `io`: asynchronous I/O reactor (e.g. Tokio's I/O driver from `enable_all`).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Capabilities {
    pub tasks: bool,
    pub timers: bool,
    pub blocking: bool,
    pub io: bool,
}

impl Capabilities {
    /// Convenience: only baseline task execution.
    pub const TASKS_ONLY: Self = Self { tasks: true, timers: false, blocking: false, io: false };

    /// Convenience: every capability.
    pub const ALL: Self = Self { tasks: true, timers: true, blocking: true, io: true };

    /// Convenience: no capabilities. Reported by an [`EngineHandle`](crate::EngineHandle)
    /// whose owning engine has been dropped (ENGINE_SPEC.md).
    pub const NONE: Self = Self { tasks: false, timers: false, blocking: false, io: false };

    /// Whether `self` satisfies every capability marked `true` in `required`.
    ///
    /// A `required` field set to `false` is treated as "not required" — the
    /// backend may or may not provide it. Used by
    /// [`EngineHandle::require`](crate::EngineHandle::require) to validate
    /// integration requirements (ENGINE_SPEC.md).
    pub fn satisfies(&self, required: Capabilities) -> bool {
        (!required.tasks || self.tasks)
            && (!required.timers || self.timers)
            && (!required.blocking || self.blocking)
            && (!required.io || self.io)
    }
}

/// Errors that can arise while constructing an engine.
#[derive(Debug, Clone)]
pub enum EngineError {
    /// A capability required by the engine is not advertised by the backend.
    MissingRequiredCapability,
    /// A backend-owned substrate could not be constructed (e.g. a Tokio
    /// runtime failed to build).
    BackendSetup(String),
}

impl std::fmt::Display for EngineError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            EngineError::MissingRequiredCapability => {
                write!(f, "backend is missing a capability required by the engine")
            }
            EngineError::BackendSetup(msg) => {
                write!(f, "backend substrate setup failed: {msg}")
            }
        }
    }
}

impl std::error::Error for EngineError {}