Enum Outcome

Source

pub enum Outcome<T, E> {
    Ok(T),
    Err(E),
    Cancelled(CancelReason),
    Panicked(PanicPayload),
}

Expand description

The four-valued outcome of a concurrent operation.

Forms a severity lattice where worse outcomes dominate: Ok < Err < Cancelled < Panicked

Variants§

§

Ok(T)

Success with a value.

§

Err(E)

Application-level error.

§

Cancelled(CancelReason)

The operation was cancelled.

§

Panicked(PanicPayload)

The operation panicked.

Implementations§

Source §

impl<T, E> Outcome<T, E>

Source

pub const fn ok(value: T) -> Outcome<T, E>

Creates a successful outcome with the given value.

§Examples

use asupersync::Outcome;

let outcome: Outcome<i32, &str> = Outcome::ok(42);
assert!(outcome.is_ok());
assert_eq!(outcome.unwrap(), 42);

Source

pub const fn err(error: E) -> Outcome<T, E>

Creates an error outcome with the given error.

§Examples

use asupersync::Outcome;

let outcome: Outcome<i32, &str> = Outcome::err("not found");
assert!(outcome.is_err());

Source

pub const fn cancelled(reason: CancelReason) -> Outcome<T, E>

Creates a cancelled outcome with the given reason.

§Examples

use asupersync::{Outcome, CancelReason};

let outcome: Outcome<i32, &str> = Outcome::cancelled(CancelReason::timeout());
assert!(outcome.is_cancelled());

Source

pub const fn panicked(payload: PanicPayload) -> Outcome<T, E>

Creates a panicked outcome with the given payload.

§Examples

use asupersync::{Outcome, PanicPayload};

let outcome: Outcome<i32, &str> = Outcome::panicked(PanicPayload::new("oops"));
assert!(outcome.is_panicked());

Source

pub const fn severity(&self) -> Severity

Returns the severity level of this outcome.

The severity levels are ordered: Ok < Err < Cancelled < Panicked. This is useful for aggregation where the worst outcome should win.

§Examples

use asupersync::{Outcome, Severity, CancelReason};

let ok: Outcome<i32, &str> = Outcome::ok(42);
let err: Outcome<i32, &str> = Outcome::err("oops");
let cancelled: Outcome<i32, &str> = Outcome::cancelled(CancelReason::timeout());

assert_eq!(ok.severity(), Severity::Ok);
assert_eq!(err.severity(), Severity::Err);
assert_eq!(cancelled.severity(), Severity::Cancelled);
assert!(ok.severity() < err.severity());

Source

pub const fn severity_u8(&self) -> u8

Returns the numeric severity level (0 = Ok, 3 = Panicked).

Prefer severity() for type-safe comparisons.

Source

pub const fn is_terminal(&self) -> bool

Returns true if this is a terminal outcome (any non-pending state).

All Outcome variants are terminal states.

Source

pub const fn is_ok(&self) -> bool

Returns true if this outcome is Ok.

§Examples

use asupersync::Outcome;

let ok: Outcome<i32, &str> = Outcome::ok(42);
let err: Outcome<i32, &str> = Outcome::err("oops");

assert!(ok.is_ok());
assert!(!err.is_ok());

Source

pub const fn is_err(&self) -> bool

Returns true if this outcome is Err.

§Examples

use asupersync::Outcome;

let err: Outcome<i32, &str> = Outcome::err("oops");
assert!(err.is_err());

Source

pub const fn is_cancelled(&self) -> bool

Returns true if this outcome is Cancelled.

§Examples

use asupersync::{Outcome, CancelReason};

let cancelled: Outcome<i32, &str> = Outcome::cancelled(CancelReason::timeout());
assert!(cancelled.is_cancelled());

Source

pub const fn is_panicked(&self) -> bool

Returns true if this outcome is Panicked.

§Examples

use asupersync::{Outcome, PanicPayload};

let panicked: Outcome<i32, &str> = Outcome::panicked(PanicPayload::new("oops"));
assert!(panicked.is_panicked());

Source

pub fn into_result(self) -> Result<T, OutcomeError<E>>

Converts this outcome to a standard Result, with cancellation and panic as errors.

This is useful when interfacing with code that expects Result.

Source

pub fn map<U, F>(self, f: F) -> Outcome<U, E>
where F: FnOnce(T) -> U,

Maps the success value using the provided function.

Source

pub fn map_err<F2, G>(self, g: G) -> Outcome<T, F2>
where G: FnOnce(E) -> F2,

Maps the error value using the provided function.

§Examples

use asupersync::Outcome;

let err: Outcome<i32, &str> = Outcome::err("short");
let mapped = err.map_err(str::len);
assert!(matches!(mapped, Outcome::Err(5)));

Source

pub fn and_then<U, F>(self, f: F) -> Outcome<U, E>
where F: FnOnce(T) -> Outcome<U, E>,

Applies a function to the success value, flattening the result.

This is the monadic bind operation, useful for chaining operations that might fail.

§Examples

use asupersync::Outcome;

fn parse_int(s: &str) -> Outcome<i32, &'static str> {
    s.parse::<i32>().map_err(|_| "parse error").into()
}

fn double(x: i32) -> Outcome<i32, &'static str> {
    Outcome::ok(x * 2)
}

let result = parse_int("21").and_then(double);
assert_eq!(result.unwrap(), 42);

let result = parse_int("abc").and_then(double);
assert!(result.is_err());

Source

pub fn ok_or_else<F2, G>(self, f: G) -> Result<T, F2>
where G: FnOnce() -> F2,

Returns the success value, or computes a fallback from a closure.

Unlike unwrap_or_else, this returns a Result that preserves the distinction between different non-Ok outcomes.

§Examples

use asupersync::{Outcome, CancelReason};

let ok: Outcome<i32, &str> = Outcome::ok(42);
let result: Result<i32, &str> = ok.ok_or_else(|| "default error");
assert_eq!(result, Ok(42));

let cancelled: Outcome<i32, &str> = Outcome::cancelled(CancelReason::timeout());
let result: Result<i32, &str> = cancelled.ok_or_else(|| "was cancelled");
assert_eq!(result, Err("was cancelled"));

Source

pub fn join(self, other: Outcome<T, E>) -> Outcome<T, E>

Joins this outcome with another, returning the outcome with higher severity.

This implements the lattice join operation for aggregating outcomes from parallel tasks. The outcome with the worst (highest) severity wins.

§Note on Value Handling

When both outcomes are Ok, this method returns self. When both are the same non-Ok severity, the first (self) is returned.

§Examples

use asupersync::{Outcome, CancelReason};

let ok1: Outcome<i32, &str> = Outcome::ok(1);
let ok2: Outcome<i32, &str> = Outcome::ok(2);
let err: Outcome<i32, &str> = Outcome::err("error");
let cancelled: Outcome<i32, &str> = Outcome::cancelled(CancelReason::timeout());

// Ok + Ok = first Ok (both same severity)
assert!(ok1.clone().join(ok2).is_ok());

// Ok + Err = Err (Err is worse)
assert!(ok1.clone().join(err.clone()).is_err());

// Err + Cancelled = Cancelled (Cancelled is worse)
assert!(err.join(cancelled).is_cancelled());