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 }