Skip to main content

PipeMonadic

Compose a list of handlers under a monad into a single handler that short-circuits on the monad's stop branch.

Overview​

Context-Generic Programming (CGP) enables pluggable trait implementations in Rust, and PipeMonadic<M, Providers> composes a handler list Providers under a monad M into one short-circuiting handler, on a context, the type the implementation runs against. Each step runs only on the previous step's continue branch, and the monad decides which branch that is. The result is a provider for Computer, AsyncComputer, TryComputer, and Handler, so it wires like any other handler. Like every CGP provider, it carries no runtime value; M and the list ride in PhantomData.

Usage​

Import it from cgp::extra::monad::providers, and the monad markers from cgp::extra::monad::monadic. None of these is in the prelude. PipeMonadic takes a monad marker and a Product! list of handler providers:

use cgp::extra::monad::providers::PipeMonadic;
use cgp::extra::monad::monadic::err::ErrMonadic;

delegate_components! {
App {
ComputerComponent:
PipeMonadic<ErrMonadic, Product![Increment, Increment, Increment]>,
}
}

Under ErrMonadic, each step runs on the previous step's Ok value and the first Err becomes the pipeline's output. The monad markers choose the branching; the naming trap there is worth re-reading, since ErrMonadic is the ?-style monad.

Examples​

A pipeline of three fallible computers, wired under ErrMonadic and called through the consumer trait:

use cgp::extra::handler::{Computer, ComputerComponent};
use cgp::prelude::*;
use cgp::extra::handler::CanCompute;
use cgp::extra::monad::monadic::err::ErrMonadic;
use cgp::extra::monad::providers::PipeMonadic;

#[cgp_computer]
pub fn increment(value: u8) -> Result<u8, &'static str> {
value.checked_add(1).ok_or("overflow")
}

pub struct App;

delegate_components! {
App {
ComputerComponent: PipeMonadic<ErrMonadic, Product![Increment, Increment, Increment]>,
}
}

check_components! {
App {
ComputerComponent: ((), u8),
}
}

pub fn demo() {
assert_eq!(App.compute(PhantomData::<()>, 1), Ok(4));
// 253 -> Ok(254) -> Ok(255) -> Err("overflow")
assert_eq!(App.compute(PhantomData::<()>, 253), Err("overflow"));
}

Each Increment returns Result<u8, &str>, and under ErrMonadic each step runs on the previous step's Ok value, so the first overflow becomes the pipeline's output and the remaining steps do not run. App is an environmental context, and Increment comes from #[cgp_computer].

Stacking monads handles nested results. These handlers return Result<Result<(), u8>, &str>, and under OkMonadicTrans<ErrMonadic> the err monad handles the outer Result while the ok layer handles the one inside it, so the pipeline stops on an outer Err or an inner Ok:

use cgp::extra::handler::{Computer, TryComputer};
use cgp::prelude::*;
use cgp::core::error::ErrorTypeProviderComponent;
use cgp::extra::monad::monadic::err::ErrMonadic;
use cgp::extra::monad::monadic::ok::{OkMonadic, OkMonadicTrans};
use cgp::extra::monad::providers::PipeMonadic;

#[cgp_computer]
pub fn return_ok_ok(_value: u8) -> Result<Result<(), u8>, &'static str> {
Ok(Ok(()))
}

#[cgp_computer]
pub fn return_ok_err(value: u8) -> Result<Result<(), u8>, &'static str> {
Ok(Err(value))
}

#[cgp_computer]
pub fn return_err(_value: u8) -> Result<Result<(), u8>, &'static str> {
Err("error")
}

pub struct App;

delegate_components! {
App {
ErrorTypeProviderComponent: UseType<&'static str>,
}
}

pub fn demo() {
let code = PhantomData::<()>;

// An inner `Ok` stops the pipeline; the last step never runs.
assert_eq!(
PipeMonadic::<
OkMonadicTrans<ErrMonadic>,
Product![ReturnOkErr, ReturnOkOk, ReturnOkErr],
>::compute(&App, code, 1),
Ok(Ok(())),
);

// An outer `Err` stops it too.
assert_eq!(
PipeMonadic::<
OkMonadicTrans<ErrMonadic>,
Product![ReturnErr, ReturnOkOk, ReturnOkErr],
>::compute(&App, code, 1),
Err("error"),
);

// Through the fallible bridge, plain `OkMonadic` behaves the same way.
assert_eq!(
PipeMonadic::<
OkMonadic,
Product![ReturnOkErr, ReturnOkOk, ReturnOkErr],
>::try_compute(&App, code, 1),
Ok(Ok(())),
);
}

The pipelines are called on the provider directly, through the Computer and TryComputer provider traits the prelude supplies, rather than wired. The last call goes through try_compute, where PipeMonadic stacks OkMonadic over ErrMonadic itself and takes the context's error, here &'static str, from the outer Result; that is why App wires an error type.

When to use it​

Reach for PipeMonadic when a pipeline's steps should short-circuit on a branch, such as an error or the first success, rather than always feeding the next step. For a pipeline where every step runs unconditionally, use PipeHandlers, which PipeMonadic<IdentMonadic, …> reduces to. When the whole chain lives in one provider body, Rust's own ? operator is clearer than any composition.

Under the hood​

PipeMonadic<M, Providers> carries the monad and the list in PhantomData:

pub struct PipeMonadic<M, Providers>(pub PhantomData<(M, Providers)>);

It implements ComputerComponent and AsyncComputerComponent by folding the list: an internal BindProviders<M> computation walks the list so the first provider runs on the input and its result is bound, through the monad, to the monadically-composed rest of the list. For [A, B, C] the result is ComposeHandlers<A, Bind<ComposeHandlers<B, Bind<C>>>>, where Bind<P> is the bind step the monad produces, such as BindErr<IdentMonadic, P> for ErrMonadic. A one-element list is its only provider, and an empty list builds nothing.

For the fallible components TryComputerComponent and HandlerComponent, it bridges through the err monad. It first maps every provider to TryPromote, demoting fallible handlers to plain computers whose output is an explicit Result; the mapper that rewrites the whole list is TryPromoteProviders, which implements MapType. It then applies M as a transformer over ErrMonadic, so the err monad handles the outer Result and M the layer inside it, composes the demoted list under that stack, and wraps the composed provider back in TryPromote to restore the fallible interface. A PipeMonadic over fallible handlers therefore short-circuits on the context's error type in addition to whatever branching M contributes. The whole fold happens during trait resolution, so the pipeline is not a runtime structure.

The ideas behind it:

  • Monadic handlers — why a pipeline short-circuits and how the monads compose.

Source​


An AI agent wrote this page using the CGP knowledge base. Its content was verified against the library's source. See How AI is used in this project.