Enum ActorResult

pub enum ActorResult<T: Actor> {
    Completed {
        actor: T,
        killed: bool,
    },
    Failed {
        actor: Option<T>,
        error: T::Error,
        phase: FailurePhase,
        killed: bool,
    },
}

Result type returned when an actor’s lifecycle completes.

ActorResult encapsulates the final state of an actor after its lifecycle has ended, whether it completed successfully or failed. This is typically obtained when awaiting the JoinHandle returned by spawn or spawn_with_mailbox_capacity. It provides detailed information about the actor’s termination state, including:

• Whether the actor completed successfully or failed
• Whether the actor was killed forcefully or stopped gracefully
• The phase in which a failure occurred (if applicable)
• The actor instance itself (if recoverable)
• The error that caused a failure (if applicable)

This enum is typically returned by actor supervision systems or when awaiting the completion of an actor’s task.

Variants

Completed

Actor completed successfully and can be recovered.

This variant indicates that the actor finished its lifecycle without errors.

Fields

actor: T

The successfully completed actor instance

killed: bool

Whether the actor was killed (true) or stopped gracefully (false)

Failed

Actor failed during one of its lifecycle phases.

This variant indicates that the actor encountered an error during execution.

Fields

actor: Option<T>

The actor instance (if recoverable), or None if not recoverable. This will be None specifically when the failure occurred during the on_start phase, as the actor wasn’t fully initialized.

error: T::Error

The error that caused the failure

phase: FailurePhase

The lifecycle phase during which the failure occurred

killed: bool

Whether the actor was killed (true) or was attempting to stop gracefully (false)

Implementations

impl<T: Actor> ActorResult<T>

pub fn is_completed(&self) -> bool

Returns true if the actor completed successfully.

This method checks if the actor finished its lifecycle without any errors, regardless of whether it was killed or stopped normally.

pub fn was_killed(&self) -> bool

Returns true if the actor was killed.

An actor is considered killed if it was terminated forcefully via the kill() method, regardless of whether it completed successfully or failed. Both ActorResult::Completed and ActorResult::Failed can have killed: true.

pub fn stopped_normally(&self) -> bool

Returns true if the actor stopped normally.

An actor stopped normally if it completed successfully without being killed, typically by processing a StopGracefully message or reaching the end of its lifecycle.

pub fn is_startup_failed(&self) -> bool

Returns true if the actor failed to start.

This indicates that the actor failed during the on_start lifecycle phase, which means it couldn’t initialize properly.

pub fn is_runtime_failed(&self) -> bool

Returns true if the actor failed during runtime.

This indicates that the actor started successfully but encountered an error during its normal operation in the on_run lifecycle phase.

pub fn is_stop_failed(&self) -> bool

Returns true if the actor failed during the stop phase.

This indicates that the actor encountered an error while trying to shut down in the on_stop lifecycle phase.

pub fn actor(&self) -> Option<&T>

Returns the actor instance if available, regardless of the result type.

If the actor completed successfully, it will always return Some(actor). If the actor failed, it may return Some(actor) or None depending on when the failure occurred and if the actor instance could be recovered.

If the failure occurred during the on_start phase, this will return None since the actor was not successfully initialized.

pub fn into_actor(self) -> Option<T>

Consumes the result and returns the actor instance if available.

This method is similar to actor() but it consumes the ActorResult, giving ownership of the actor to the caller if available.

pub fn error(&self) -> Option<&T::Error>

Returns the error if the result represents a failure.

If the actor completed successfully, this returns None. If the actor failed, this returns Some(error) containing the error that caused the failure.

pub fn into_error(self) -> Option<T::Error>

Consumes the result and returns the error if it represents a failure.

This method is similar to error() but it consumes the ActorResult, giving ownership of the error to the caller if available.

pub fn is_failed(&self) -> bool

Returns true if the result represents any kind of failure.

This is the logical opposite of is_completed().

pub fn has_actor(&self) -> bool

Returns true if the result contains an actor instance.

This checks if the actor instance is available, regardless of whether the actor completed successfully or failed.

pub fn to_result(self) -> Result<T, T::Error>

Converts to a standard Result, preserving the actor on success

This transforms the ActorResult<T> into a Result<T, T::Error>, which is useful for integrating with Rust’s standard error handling patterns.

Trait Implementations

impl<T: Debug + Actor> Debug for ActorResult<T>

where T::Error: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Actor> From<ActorResult<T>> for (Option<T>, Option<T::Error>)

Conversion from ActorResult to a tuple of (Option<Actor>, Option<Error>)

This allows extracting both the actor instance and error (if any) in a single operation. Useful for pattern matching and destructuring in supervision contexts.

Example

let (maybe_actor, maybe_error) = actor_result.into();
if let Some(actor) = maybe_actor {
    // The actor is available (either completed or recovered after failure)
}
if let Some(error) = maybe_error {
    // An error occurred
}

fn from(result: ActorResult<T>) -> Self

Converts to this type from the input type.