ferrum_interfaces/scheduler/
prefix_restore.rs

1//! Single-use scheduler preparation for an independent state restore stage.
2
3use std::any::Any;
4
5use ferrum_types::{FerrumError, RequestId, Result};
6
7/// A scheduler-owned preparation, created before asynchronous device work.
8///
9/// The implementation proof is intentionally opaque to the engine. It must
10/// bind the exact admission incarnation and logical work generation, rather
11/// than authorizing a later lookup by request id alone. Its destructor releases
12/// any scheduling hold without committing progress. This value is not Clone
13/// or serializable and does not prove that device restoration has completed.
14#[must_use = "commit after successful restore publication, or drop to abandon it"]
15pub struct PreparedPrefixRestore {
16    request_id: RequestId,
17    expected_offset: usize,
18    prompt_tokens: usize,
19    proof: Box<dyn Any + Send + Sync>,
20}
21
22impl PreparedPrefixRestore {
23    /// Implementer constructor. The receiving scheduler must validate the
24    /// private proof type and its identity on every commit.
25    pub fn new<T: Any + Send + Sync>(
26        request_id: RequestId,
27        expected_offset: usize,
28        prompt_tokens: usize,
29        proof: T,
30    ) -> Self {
31        Self {
32            request_id,
33            expected_offset,
34            prompt_tokens,
35            proof: Box::new(proof),
36        }
37    }
38
39    pub fn request_id(&self) -> &RequestId {
40        &self.request_id
41    }
42
43    pub const fn expected_offset(&self) -> usize {
44        self.expected_offset
45    }
46
47    pub const fn prompt_tokens(&self) -> usize {
48        self.prompt_tokens
49    }
50
51    /// Inspect an implementation proof without consuming its scheduling hold.
52    /// A foreign proof remains an error, never authority for a matching id.
53    pub fn proof_ref<T: Any + Send + Sync>(&self) -> Result<&T> {
54        self.proof.downcast_ref::<T>().ok_or_else(|| {
55            FerrumError::scheduler("Prefix restore preparation belongs to another scheduler type")
56        })
57    }
58
59    /// Consume the implementation's private proof. A foreign scheduler or
60    /// proof type cannot silently become authority for a matching request id.
61    pub fn into_proof<T: Any + Send + Sync>(self) -> Result<T> {
62        self.proof.downcast::<T>().map(|proof| *proof).map_err(|_| {
63            FerrumError::scheduler("Prefix restore preparation belongs to another scheduler type")
64        })
65    }
66}
67
68impl std::fmt::Debug for PreparedPrefixRestore {
69    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
70        f.debug_struct("PreparedPrefixRestore")
71            .field("request_id", &self.request_id)
72            .field("expected_offset", &self.expected_offset)
73            .field("prompt_tokens", &self.prompt_tokens)
74            .finish_non_exhaustive()
75    }
76}
ferrum_interfaces/scheduler/prefix_restore.rs

ferrum_interfaces/scheduler/
prefix_restore.rs
