Skip to main content

Supervisor

Struct Supervisor 

Source
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>

Source

pub fn try_new(lifecycle: L, config: Config) -> Result<Self, ConfigError>

Validate before constructing channels or starting lifecycle work.

Source

pub fn try_start(lifecycle: L, config: Config) -> Result<Self, ConfigError>

Source

pub fn start(lifecycle: L, config: Config) -> Self

Source

pub fn new(lifecycle: L, config: Config) -> Self

Construct without spawning tasks, so hooks and setters can be configured first.

Source

pub fn begin(&self)

Start supervision once. Acquisition starts an unstarted supervisor automatically.

Source

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.

Source

pub fn subscribe(&self) -> Receiver<ResourceStatus<L::Resource>>

Source

pub fn current(&self) -> Option<ResourceHandle<L::Resource>>

Source

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.

Source

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.

Source

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.

Source

pub fn value<T: Clone + Send + Sync + 'static>(&self, name: &str) -> Option<T>

Source

pub fn set_on_resource_created(&self, hook: CreatedHook<L::Resource, L::Error>)

Source

pub fn is_connected(&self) -> bool

Source

pub fn stopped(&self) -> Receiver<bool>

Source

pub fn state(&self) -> ResourceState

Source

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.

Source

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.

Source

pub async fn acquire( &self, ) -> Result<ResourceHandle<L::Resource>, Error<L::Error>>

Source

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.

Source

pub fn request_recovery( &self, handle: &ResourceHandle<L::Resource>, terminal: bool, )

Request recovery without waiting for teardown.

Source

pub async fn recover( &self, handle: &ResourceHandle<L::Resource>, terminal: bool, ) -> Result<(), Error<L::Error>>

Wait for bounded teardown. Does not wait for reconnection.

Source

pub async fn recover_current( &self, terminal: bool, ) -> Result<(), Error<L::Error>>

Source

pub async fn execute<F, Fut, T>( &self, operation: F, ) -> Result<T, Error<L::Error>>
where F: FnOnce(Arc<L::Resource>) -> Fut, Fut: Future<Output = Result<T, 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.

Source

pub async fn execute_with_timeout<F, Fut, T>( &self, duration: Duration, operation: F, ) -> Result<T, Error<L::Error>>
where F: FnOnce(Arc<L::Resource>) -> Fut, Fut: Future<Output = Result<T, 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.

Source

pub async fn execute_with_retry<F, Fut, T, P>( &self, policy: RetryPolicy, operation: F, retry_if: P, ) -> Result<T, Error<L::Error>>
where F: FnMut(Arc<L::Resource>) -> Fut, Fut: Future<Output = Result<T, L::Error>>, P: FnMut(&L::Error) -> bool,

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.

Source

pub async fn stop(&self)

Idempotent, cancellation-safe shutdown. Clears resource-derived caches, preserving stored configuration and registrations. External handles and abandoned timed-out hook tasks can retain resources beyond this return.

Trait Implementations§

Source§

impl<L: Lifecycle> Clone for Supervisor<L>

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more

Auto Trait Implementations§

§

impl<L> !RefUnwindSafe for Supervisor<L>

§

impl<L> !UnwindSafe for Supervisor<L>

§

impl<L> Freeze for Supervisor<L>

§

impl<L> Send for Supervisor<L>

§

impl<L> Sync for Supervisor<L>

§

impl<L> Unpin for Supervisor<L>

§

impl<L> UnsafeUnpin for Supervisor<L>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more