pub struct Supervisor<L: Lifecycle> { /* private fields */ }Expand description
Cloneable client-facing handle. Start inside a Tokio runtime.
Dropping the last supervisor requests shutdown; stop().await waits for teardown.
Implementations§
Source§impl<L: Lifecycle> Supervisor<L>
impl<L: Lifecycle> Supervisor<L>
Sourcepub fn try_new(lifecycle: L, config: Config) -> Result<Self, ConfigError>
pub fn try_new(lifecycle: L, config: Config) -> Result<Self, ConfigError>
Validate before constructing channels or starting lifecycle work.
pub fn try_start(lifecycle: L, config: Config) -> Result<Self, ConfigError>
pub fn start(lifecycle: L, config: Config) -> Self
Sourcepub fn new(lifecycle: L, config: Config) -> Self
pub fn new(lifecycle: L, config: Config) -> Self
Construct without spawning tasks, so hooks and setters can be configured first.
Sourcepub fn begin(&self)
pub fn begin(&self)
Start supervision once. Acquisition starts an unstarted supervisor automatically.
Sourcepub async fn restart(&self) -> bool
pub async fn restart(&self) -> bool
Restart a fully stopped supervisor, preserving setters and public handles. Returns false if it is already running. Pools remain permanently stopped.
pub fn subscribe(&self) -> Receiver<ResourceStatus<L::Resource>>
pub fn current(&self) -> Option<ResourceHandle<L::Resource>>
Sourcepub fn with_latest<T>(&self, read: impl FnOnce(&L::Resource) -> T) -> Option<T>
pub fn with_latest<T>(&self, read: impl FnOnce(&L::Resource) -> T) -> Option<T>
Read an owned attribute from the latest created resource, even during recovery. Returns None after awaited stop; stored values remain readable.
Sourcepub fn set_attribute(
&self,
name: impl Into<String>,
setter: AttributeSetter<L::Resource>,
)
pub fn set_attribute( &self, name: impl Into<String>, setter: AttributeSetter<L::Resource>, )
Replay a synchronous attribute setter on the latest resource and all replacements. Setters must be short, nonblocking, and must not reenter this supervisor.
Sourcepub fn set_value<T: Clone + Send + Sync + 'static>(
&self,
name: impl Into<String>,
value: T,
apply: impl Fn(&L::Resource, &T) + Send + Sync + 'static,
)
pub fn set_value<T: Clone + Send + Sync + 'static>( &self, name: impl Into<String>, value: T, apply: impl Fn(&L::Resource, &T) + Send + Sync + 'static, )
Store a typed value that is readable before creation and replay it on replacement.
pub fn value<T: Clone + Send + Sync + 'static>(&self, name: &str) -> Option<T>
pub fn set_on_resource_created(&self, hook: CreatedHook<L::Resource, L::Error>)
pub fn is_connected(&self) -> bool
pub fn stopped(&self) -> Receiver<bool>
pub fn state(&self) -> ResourceState
Sourcepub fn failure(&self) -> Option<Arc<L::Error>>
pub fn failure(&self) -> Option<Arc<L::Error>>
Inspect the latched cause without implicitly resetting it. Error values may contain secrets; the framework does not format this cause in logs.
Sourcepub fn reset_failure(&self) -> bool
pub fn reset_failure(&self) -> bool
Explicitly permit a failed lifecycle to try again after teardown. Does not restart a stopped supervisor. Stop takes precedence over reset.
pub async fn acquire( &self, ) -> Result<ResourceHandle<L::Resource>, Error<L::Error>>
Sourcepub async fn acquire_with_timeout(
&self,
duration: Duration,
) -> Result<ResourceHandle<L::Resource>, Error<L::Error>>
pub async fn acquire_with_timeout( &self, duration: Duration, ) -> Result<ResourceHandle<L::Resource>, Error<L::Error>>
Acquire readiness within one overall timeout, following lifecycle recovery. Zero returns Timeout without starting supervision; an already stopped supervisor returns Stopped. The timeout starts when this future is polled.
Sourcepub fn request_recovery(
&self,
handle: &ResourceHandle<L::Resource>,
terminal: bool,
)
pub fn request_recovery( &self, handle: &ResourceHandle<L::Resource>, terminal: bool, )
Request recovery without waiting for teardown.
Sourcepub async fn recover(
&self,
handle: &ResourceHandle<L::Resource>,
terminal: bool,
) -> Result<(), Error<L::Error>>
pub async fn recover( &self, handle: &ResourceHandle<L::Resource>, terminal: bool, ) -> Result<(), Error<L::Error>>
Wait for bounded teardown. Does not wait for reconnection.
pub async fn recover_current( &self, terminal: bool, ) -> Result<(), Error<L::Error>>
Sourcepub async fn execute<F, Fut, T>(
&self,
operation: F,
) -> Result<T, Error<L::Error>>
pub async fn execute<F, Fut, T>( &self, operation: F, ) -> Result<T, Error<L::Error>>
Run once. By default failures request recovery and return the original error
without replay; operation_failure can retain a healthy generation instead.
Dropping this future cancels the operation; protocol-specific cancellation safety
remains the client’s responsibility. Shutdown cancels operations driven by this method.
Sourcepub async fn execute_with_timeout<F, Fut, T>(
&self,
duration: Duration,
operation: F,
) -> Result<T, Error<L::Error>>
pub async fn execute_with_timeout<F, Fut, T>( &self, duration: Duration, operation: F, ) -> Result<T, Error<L::Error>>
Run once within an overall timeout covering readiness, the operation and any bounded failure teardown. Never replay. Zero does not start work. Shutdown takes precedence. Expiry drops the operation future; adapters remain responsible for poisoning interrupted protocol exchanges.
Sourcepub async fn execute_with_retry<F, Fut, T, P>(
&self,
policy: RetryPolicy,
operation: F,
retry_if: P,
) -> Result<T, Error<L::Error>>
pub async fn execute_with_retry<F, Fut, T, P>( &self, policy: RetryPolicy, operation: F, retry_if: P, ) -> Result<T, Error<L::Error>>
Retry an operation only when retry_if accepts its error and attempts remain.
Each invocation of operation must create a fresh future and safely repeat
the remote action. The next attempt waits for lifecycle readiness; a retained
healthy generation may be reused without replacement.
Exhaustion returns the last operation error; the overall deadline returns
Error::Timeout. Shutdown returns Error::Stopped; cancellation drops
the active attempt without starting another. As with Self::execute,
resource-specific cancellation safety is the adapter’s responsibility.
Terminal classification controls teardown, not whether replay is allowed.