loeres_device/workspace.rs
1//! Caller-owned typed workspace lifecycle (RFC 005).
2//!
3//! [`DeviceWorkspace`] is the single essential lifecycle method (reset-on-entry);
4//! [`DeviceWorkspaceDiagnostic`] is an always-available, ungated compact-diagnostic
5//! extension; [`WorkspaceFor`] associates a solver family with its workspace type
6//! and footprint. Concrete workspaces and solver kernels are RFC 006-owned.
7
8use loeres::DiagnosticSnapshot;
9
10/// Caller-owned solver workspace lifecycle.
11///
12/// A device workspace is owned by the caller, passed by unique `&mut`, and safe
13/// to discard or immediately reuse after any solver outcome (poison-free reuse,
14/// RFC 005 §7). The lifecycle core is a single logical initialization step.
15pub trait DeviceWorkspace {
16 /// Logically initialize the workspace for a fresh solve entry.
17 ///
18 /// Overwrite-on-use: this must not require zeroing the whole buffer unless a
19 /// specific field must be initialized for correctness.
20 fn reset_for_entry(&mut self);
21}
22
23/// Always-available compact diagnostics for a device workspace.
24///
25/// Kept separate from [`DeviceWorkspace`] so the lifecycle core stays minimal.
26/// This accessor and [`DiagnosticSnapshot`] are never gated by the
27/// `diagnostic-snapshot` feature (RFC 005 §10, decision M4); that feature governs
28/// only richer/optional diagnostics.
29pub trait DeviceWorkspaceDiagnostic {
30 /// A compact diagnostic snapshot of the current workspace state.
31 fn diagnostic(&self) -> DiagnosticSnapshot;
32}
33
34/// Associates a solver family `P` with its workspace type and footprint.
35///
36/// The concrete `P` problem families and `Workspace` shapes are RFC 006-owned;
37/// this trait fixes only the lifecycle/sizing contract.
38pub trait WorkspaceFor<P> {
39 /// The workspace type for problem family `P`.
40 type Workspace: DeviceWorkspace;
41
42 /// The required workspace footprint in bytes.
43 ///
44 /// May be computed from `core::mem::size_of::<Self::Workspace>()` (decision M8).
45 fn required_workspace_bytes() -> usize;
46}
47
48#[cfg(test)]
49mod tests;