error_rail/async_ext/
context_future.rs

1//! Future wrappers for lazy context evaluation.
2//!
3//! This module provides `ContextFuture`, which wraps a `Future<Output = Result<T, E>>`
4//! and attaches error context only when the future resolves to an error.
5
6use core::future::Future;
7use core::pin::Pin;
8use core::task::{Context, Poll};
9
10use futures_core::future::FusedFuture;
11
12use pin_project_lite::pin_project;
13
14use crate::traits::IntoErrorContext;
15use crate::types::ComposableError;
16
17pin_project! {
18    /// A Future wrapper that attaches error context lazily.
19    ///
20    /// The context is only evaluated when the inner future resolves to an error,
21    /// maintaining zero-cost on the success path.
22    ///
23    /// # Cancel Safety
24    ///
25    /// `ContextFuture` is cancel-safe if the inner future is cancel-safe.
26    /// The `context_fn` is only called when `poll` returns `Poll::Ready(Err(_))`.
27    ///
28    /// # Examples
29    ///
30    /// ```rust
31    /// use error_rail::prelude_async::*;
32    ///
33    /// async fn example() -> BoxedResult<i32, &'static str> {
34    ///     async { Err("failed") }
35    ///         .ctx("operation context")
36    ///         .await
37    ///         .map_err(Box::new)
38    /// }
39    /// ```
40    #[must_use = "futures do nothing unless polled"]
41    pub struct ContextFuture<Fut, F> {
42        #[pin]
43        future: Fut,
44        context_fn: Option<F>,
45    }
46}
47
48impl<Fut, F> ContextFuture<Fut, F> {
49    /// Creates a new `ContextFuture` with the given future and context generator.
50    #[inline]
51    pub const fn new(future: Fut, context_fn: F) -> Self {
52        Self { future, context_fn: Some(context_fn) }
53    }
54}
55
56impl<Fut, F, C, T, E> Future for ContextFuture<Fut, F>
57where
58    Fut: Future<Output = Result<T, E>>,
59    F: FnOnce() -> C,
60    C: IntoErrorContext,
61{
62    type Output = Result<T, ComposableError<E>>;
63
64    #[inline]
65    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
66        let this = self.project();
67
68        match this.future.poll(cx) {
69            Poll::Pending => Poll::Pending,
70            Poll::Ready(Ok(value)) => Poll::Ready(Ok(value)),
71            Poll::Ready(Err(err)) => {
72                // SAFETY: context_fn is Some until first error completion
73                let context_fn = this
74                    .context_fn
75                    .take()
76                    .expect("ContextFuture polled after completion");
77                Poll::Ready(Err(ComposableError::new(err).with_context(context_fn())))
78            },
79        }
80    }
81}
82
83impl<Fut, F, C, T, E> FusedFuture for ContextFuture<Fut, F>
84where
85    Fut: FusedFuture<Output = Result<T, E>>,
86    F: FnOnce() -> C,
87    C: IntoErrorContext,
88{
89    #[inline]
90    fn is_terminated(&self) -> bool {
91        self.context_fn.is_none() || self.future.is_terminated()
92    }
93}
error_rail/async_ext/context_future.rs

error_rail/async_ext/
context_future.rs
