lib

Core libraries for Radroots
git clone https://radroots.dev/git/lib.git
Log | Files | Refs | README

host.rs (2972B)


      1 use core::{future::Future, pin::Pin};
      2 use std::boxed::Box;
      3 
      4 #[cfg(target_arch = "wasm32")]
      5 pub(crate) use std::rc::Rc as Shared;
      6 #[cfg(not(target_arch = "wasm32"))]
      7 pub(crate) use std::sync::Arc as Shared;
      8 
      9 /// An owned host future. Browser futures remain on their originating thread.
     10 #[cfg(not(target_arch = "wasm32"))]
     11 pub type HostFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;
     12 /// An owned host future. Browser futures remain on their originating thread.
     13 #[cfg(target_arch = "wasm32")]
     14 pub type HostFuture<'a, T> = Pin<Box<dyn Future<Output = T> + 'a>>;
     15 
     16 /// Native hosts are thread safe; browser hosts may retain local callbacks.
     17 #[cfg(not(target_arch = "wasm32"))]
     18 pub trait HostBound: Send + Sync {}
     19 #[cfg(not(target_arch = "wasm32"))]
     20 impl<T: Send + Sync + ?Sized> HostBound for T {}
     21 
     22 /// Native hosts are thread safe; browser hosts may retain local callbacks.
     23 #[cfg(target_arch = "wasm32")]
     24 pub trait HostBound {}
     25 #[cfg(target_arch = "wasm32")]
     26 impl<T: ?Sized> HostBound for T {}
     27 
     28 /// Resources exclusively owned by one session, without a library-owned runtime.
     29 ///
     30 /// Hooks must retain progress across cancellation: repeating an unfinished hook
     31 /// resumes it, including a result already obtained before its waiter was lost.
     32 /// Successful hooks are not repeated. A failed hook must leave its resources
     33 /// available for retry. No hook may report completion while its work is detached.
     34 /// Concrete host qualification must exercise these requirements independently.
     35 pub trait SessionHost: HostBound {
     36     /// Starts the configured bounded workers. Repeat calls resume partial start.
     37     /// No command admission is enabled until this hook succeeds.
     38     fn start(&self) -> HostFuture<'_, crate::Result<()>>;
     39 
     40     /// Stops new background work and quiesces workers. Retain unresolved signing
     41     /// and obtained results in their journal before releasing their work permits.
     42     /// Existing permitted work must remain able to reach its safe boundary.
     43     fn quiesce(&self) -> HostFuture<'_, crate::Result<()>>;
     44 
     45     /// Drains the host's owned jobs after dispatch has been quiesced. A failed
     46     /// protected capture must keep its original material and resource permits;
     47     /// return recovery rather than claiming successful disposal. Repeated calls
     48     /// resume the same retained work. Hosts without an owned job set do nothing.
     49     fn drain(&self) -> HostFuture<'_, crate::Result<()>> {
     50         Box::pin(async { Ok(()) })
     51     }
     52 
     53     /// Disconnects every owned transport and its authentication state.
     54     fn disconnect(&self) -> HostFuture<'_, crate::Result<()>>;
     55 
     56     /// Disposes retained callbacks and subscriptions on their owning thread.
     57     fn dispose_callbacks(&self) -> HostFuture<'_, crate::Result<()>>;
     58 
     59     /// Closes storage after workers, admitted work, transports and callbacks.
     60     /// Completion must include any required checkpoint and authority release.
     61     fn close_storage(&self) -> HostFuture<'_, crate::Result<()>>;
     62 }