egui_async/

bind.rs

//! Core state management for asynchronous operations.
//!
//! This module provides the `Bind` struct, which is the heart of `egui-async`. It acts as a
//! state machine to manage the lifecycle of a `Future`, from initiation to completion, and
//! holds the resulting data or error.
use std::{fmt::Debug, future::Future};

use atomic_float::AtomicF64;
use tokio::sync::oneshot;
use tracing::warn;

/// The `egui` time of the current frame, updated by `EguiAsyncPlugin`.
pub static CURR_FRAME: AtomicF64 = AtomicF64::new(0.0);
/// The `egui` time of the previous frame, updated by `EguiAsyncPlugin`.
pub static LAST_FRAME: AtomicF64 = AtomicF64::new(0.0);

/// A lazily initialized Tokio runtime for executing async tasks on non-WASM targets.
///
/// This is the default runtime. It is only created once a task is spawned without another
/// runtime chosen through [`set_global_runtime`] or [`Bind::set_runtime`].
#[cfg(not(target_family = "wasm"))]
pub static ASYNC_RUNTIME: std::sync::LazyLock<tokio::runtime::Runtime> =
    std::sync::LazyLock::new(|| {
        tokio::runtime::Runtime::new().expect("Failed to create Tokio runtime.")
    });

/// The runtime set by [`set_global_runtime`], if any.
#[cfg(not(target_family = "wasm"))]
static GLOBAL_RUNTIME: std::sync::OnceLock<tokio::runtime::Handle> = std::sync::OnceLock::new();

/// Sets the Tokio runtime that every `Bind` spawns its tasks onto, in place of the built-in
/// [`ASYNC_RUNTIME`]. A `Bind` with its own runtime ([`Bind::set_runtime`]) still uses that.
///
/// Call this once at startup, before the first request. Tasks already spawned stay on the
/// runtime they were spawned on, and the built-in runtime is never created if no task needs it.
///
/// The runtime must stay alive and keep running tasks for as long as `Bind`s use it. A
/// multi-thread runtime runs tasks on its worker threads, but a current-thread runtime only runs
/// them while a thread is blocked on it. Requests spawned onto a runtime that has shut down are
/// cancelled, and the `Bind` returns to `Idle`.
///
/// Native only: on WASM, tasks always run on the browser's event loop.
///
/// # Errors
/// Returns the handle if a global runtime was already set.
///
/// # Example
/// ```
/// let runtime = tokio::runtime::Runtime::new().expect("failed to create runtime");
/// egui_async::set_global_runtime(runtime.handle().clone()).expect("global runtime already set");
///
/// // Every `Bind` now spawns its tasks onto `runtime`, which must outlive them.
/// ```
#[cfg(not(target_family = "wasm"))]
pub fn set_global_runtime(handle: tokio::runtime::Handle) -> Result<(), tokio::runtime::Handle> {
    GLOBAL_RUNTIME.set(handle)
}

/// Returns the runtime that a `Bind` without its own runtime spawns tasks onto.
#[cfg(not(target_family = "wasm"))]
fn global_runtime() -> &'static tokio::runtime::Handle {
    GLOBAL_RUNTIME
        .get()
        .unwrap_or_else(|| ASYNC_RUNTIME.handle())
}

/// A global holder for the `egui::Context`, used to request repaints from background tasks.
///
/// This is initialized once by `EguiAsyncPlugin`.
///
/// Not available on threaded WASM (`wasm32` with the `atomics` target feature), where
/// `egui::Context` is neither `Send` nor `Sync`. There, the context is kept in a thread-local
/// on the thread that runs the plugin instead.
#[cfg(all(
    feature = "egui",
    not(all(target_arch = "wasm32", target_feature = "atomics"))
))]
pub static CTX: std::sync::OnceLock<egui::Context> = std::sync::OnceLock::new();

#[cfg(all(feature = "egui", target_arch = "wasm32", target_feature = "atomics"))]
thread_local! {
    /// Thread-local holder for the `egui::Context` on threaded WASM.
    ///
    /// Only the thread that runs `EguiAsyncPlugin` (the main thread) has a context. Tasks are
    /// spawned with `wasm_bindgen_futures::spawn_local`, which polls them on the thread that
    /// spawned them, so results requested from that thread are delivered where the context lives.
    static CTX: std::cell::OnceCell<egui::Context> = const { std::cell::OnceCell::new() };
}

/// Stores the `egui::Context` used to request repaints, if it is not already set.
#[cfg(feature = "egui")]
pub(crate) fn init_ctx(ctx: &egui::Context) {
    #[cfg(not(all(target_arch = "wasm32", target_feature = "atomics")))]
    CTX.get_or_init(|| ctx.clone());

    #[cfg(all(target_arch = "wasm32", target_feature = "atomics"))]
    let _ = CTX.try_with(|cell| {
        cell.get_or_init(|| ctx.clone());
    });
}

/// Requests a repaint of the stored `egui::Context`, if one has been set.
///
/// On threaded WASM, only the thread that runs `EguiAsyncPlugin` can request a repaint; on any
/// other thread this does nothing.
fn request_repaint() {
    #[cfg(all(
        feature = "egui",
        not(all(target_arch = "wasm32", target_feature = "atomics"))
    ))]
    if let Some(ctx) = CTX.get() {
        ctx.request_repaint();
    }

    #[cfg(all(feature = "egui", target_arch = "wasm32", target_feature = "atomics"))]
    let _ = CTX.try_with(|cell| {
        if let Some(ctx) = cell.get() {
            ctx.request_repaint();
        }
    });
}

/// Represents the execution state of an asynchronous operation managed by `Bind`.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum State {
    /// No operation is running, and no data is available from a previous run.
    #[default]
    Idle,
    /// An operation is currently in-flight.
    Pending,
    /// An operation has completed, and its result (success or error) is available.
    Finished,
}

/// Represents the detailed state of a `Bind`, including available data.
pub enum StateWithData<'a, T, E> {
    /// No operation is running.
    Idle,
    /// An operation is currently in-flight.
    Pending,
    /// An operation has completed with a successful result.
    Finished(&'a T),
    /// An operation has completed with an error.
    Failed(&'a E),
}

impl<T: Debug, E: Debug> Debug for StateWithData<'_, T, E> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            StateWithData::Idle => f.write_str("Idle"),
            StateWithData::Pending => f.write_str("Pending"),
            StateWithData::Finished(t) => f.debug_tuple("Finished").field(t).finish(),
            StateWithData::Failed(e) => f.debug_tuple("Failed").field(e).finish(),
        }
    }
}

bitflags::bitflags! {
    /// Configuration flags for `Bind` behavior.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct ConfigFlags: u8 {
        /// If `true`, the `data` from a `Finished` state is preserved even if the `Bind` instance
        /// is not polled for one or more frames. If `false`, the data is cleared.
        const RETAIN = 0b0000_0001;
        /// Opt-in: Physically abort the background task when the Bind is aborted,
        /// cleared, or a new request is made.
        ///
        /// On native targets, the Tokio task is aborted. On WASM, the spawned local
        /// task is dropped the next time the executor polls it, without polling the
        /// future again.
        ///
        /// **Warning:** This terminates the task at its current `.await` point. If the
        /// future has critical side effects (e.g., I/O, cleanup), they may not complete.
        const ABORT  = 0b0000_0010;
    }
}

impl Default for ConfigFlags {
    fn default() -> Self {
        Self::empty()
    }
}

/// Internal container to keep the receiver and its control handle synchronized.
/// This should exist only when the state is `Pending`.
struct InFlight<T, E> {
    /// The receiving end of a one-shot channel used to get the result from the background task.
    recv: oneshot::Receiver<Result<T, E>>,

    /// The abort handle for the spawned task (native only).
    #[cfg(not(target_family = "wasm"))]
    handle: tokio::task::AbortHandle,

    /// Signals the spawned task to stop (WASM only). Dropping it unsent lets the task run on.
    #[cfg(target_family = "wasm")]
    abort_tx: oneshot::Sender<()>,
}

impl<T, E> Debug for InFlight<T, E> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let mut out = f.debug_struct("InFlight");
        out.field("recv", &"oneshot::Receiver<...>");

        #[cfg(not(target_family = "wasm"))]
        out.field("handle", &self.handle);

        #[cfg(target_family = "wasm")]
        out.field("abort_tx", &"oneshot::Sender<()>");

        out.finish()
    }
}

impl<T, E> InFlight<T, E> {
    fn abort(self) {
        #[cfg(not(target_family = "wasm"))]
        self.handle.abort();

        // An error means the task already finished, so there is nothing to stop.
        #[cfg(target_family = "wasm")]
        let _ = self.abort_tx.send(());
    }

    fn poll_result(&mut self) -> Result<Result<T, E>, oneshot::error::TryRecvError> {
        self.recv.try_recv()
    }
}

/// A state manager for a single asynchronous operation, designed for use with `egui`.
///
/// `Bind` tracks the lifecycle of a `Future` and stores its `Result<T, E>`. It acts as a
/// bridge between the immediate-mode UI and the background async task, ensuring the UI
/// can react to changes in state (e.g., show a spinner while `Pending`, display the
/// result when `Finished`, or show an error).
pub struct Bind<T, E> {
    /// The `egui` time of the most recent frame where this `Bind` was polled.
    drawn_time_last: f64,
    /// The `egui` time of the second most recent frame where this `Bind` was polled.
    drawn_time_prev: f64,

    /// The result of the completed async operation. `None` if the task is not `Finished`.
    pub(crate) data: Option<Result<T, E>>,
    in_flight: Option<InFlight<T, E>>,

    /// The current execution state of the async operation.
    pub(crate) state: State,
    /// The `egui` time when the most recent operation was started.
    last_start_time: f64,
    /// The `egui` time when the most recent operation was completed.
    last_complete_time: f64,

    /// Configuration option flags
    pub config: ConfigFlags,

    /// The runtime this `Bind` spawns tasks onto, overriding the global runtime (native only).
    #[cfg(not(target_family = "wasm"))]
    runtime: Option<tokio::runtime::Handle>,

    /// A counter for how many times an async operation has been started.
    times_executed: usize,
}

impl<T, E> Debug for Bind<T, E> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let mut out = f.debug_struct("Bind");
        let mut out = out
            .field("state", &self.state)
            .field("config", &self.config)
            .field("drawn_time_last", &self.drawn_time_last)
            .field("drawn_time_prev", &self.drawn_time_prev)
            .field("last_start_time", &self.last_start_time)
            .field("last_complete_time", &self.last_complete_time)
            .field("times_executed", &self.times_executed);

        #[cfg(not(target_family = "wasm"))]
        {
            out = out.field("runtime", &self.runtime);
        }

        // Avoid printing the full data/recv content for cleaner debug output.
        if self.data.is_some() {
            out = out.field("data", &"Some(...)");
        } else {
            out = out.field("data", &"None");
        }

        if let Some(in_flight) = &self.in_flight {
            out = out.field("in_flight", in_flight);
        } else {
            out = out.field("in_flight", &"None");
        }

        out.finish()
    }
}

impl<T: 'static, E: 'static> Default for Bind<T, E> {
    /// Creates a default `Bind` instance in an `Idle` state.
    ///
    /// The `retain` flag is set to `false`. This implementation does not require `T` or `E`
    /// to implement `Default`.
    fn default() -> Self {
        Self::new(false)
    }
}

/// Runs `task` until it completes or a stop signal arrives on `abort_rx`.
///
/// The receiver is polled before the task: `Ok` drops the task without polling it again, while
/// `Err` (the sender was dropped unsent) stops listening and lets the task run to completion.
#[cfg(target_family = "wasm")]
async fn abortable(task: impl Future<Output = ()>, abort_rx: oneshot::Receiver<()>) {
    use std::task::Poll;

    let mut task = std::pin::pin!(task);
    let mut abort_rx = Some(abort_rx);

    std::future::poll_fn(|cx| {
        if let Some(rx) = abort_rx.as_mut() {
            match std::pin::Pin::new(rx).poll(cx) {
                Poll::Ready(Ok(())) => return Poll::Ready(()),
                Poll::Ready(Err(_)) => abort_rx = None,
                Poll::Pending => {}
            }
        }
        task.as_mut().poll(cx)
    })
    .await;
}

/// A trait alias for `Send` on native targets.
///
/// On WASM, this trait has no bounds, allowing non-`Send` types to be used in `Bind`
/// since WASM is single-threaded.
#[cfg(not(target_family = "wasm"))]
pub trait MaybeSend: Send {}
#[cfg(not(target_family = "wasm"))]
impl<T: Send> MaybeSend for T {}

/// A trait alias with no bounds on WASM targets.
///
/// This allows `Bind` to work with `!Send` futures and data types in a single-threaded
/// web environment.
#[cfg(target_family = "wasm")]
pub trait MaybeSend {}
#[cfg(target_family = "wasm")]
impl<T> MaybeSend for T {}

impl<T: 'static, E: 'static> Bind<T, E> {
    /// Creates a new `Bind` instance with a specific retain policy.
    ///
    /// # Parameters
    /// - `retain`: If `true`, the result of the operation is kept even if the `Bind`
    ///   is not polled in a frame. If `false`, the result is cleared if not polled
    ///   for one frame, returning the `Bind` to an `Idle` state.
    #[must_use]
    pub const fn new(retain: bool) -> Self {
        Self {
            drawn_time_last: 0.0,
            drawn_time_prev: 0.0,

            data: None,
            in_flight: None,

            state: State::Idle,
            last_start_time: 0.0,
            last_complete_time: f64::MIN, // Set to a very low value to ensure `since_completed` is large initially.

            config: if retain {
                ConfigFlags::RETAIN
            } else {
                ConfigFlags::empty()
            },

            #[cfg(not(target_family = "wasm"))]
            runtime: None,

            times_executed: 0,
        }
    }

    /// Sets the Tokio runtime this `Bind` spawns its tasks onto, for use when building a `Bind`.
    ///
    /// See [`Bind::set_runtime`].
    ///
    /// # Example
    /// ```
    /// # use egui_async::Bind;
    /// let runtime = tokio::runtime::Runtime::new().expect("failed to create runtime");
    /// let bind: Bind<String, String> = Bind::new(false).with_runtime(runtime.handle().clone());
    /// ```
    #[cfg(not(target_family = "wasm"))]
    #[must_use]
    pub fn with_runtime(mut self, handle: tokio::runtime::Handle) -> Self {
        self.runtime = Some(handle);
        self
    }

    /// Returns the Tokio runtime set for this `Bind`, if any.
    ///
    /// `None` means it uses the global runtime: the one set with [`set_global_runtime`], or the
    /// built-in [`ASYNC_RUNTIME`].
    #[cfg(not(target_family = "wasm"))]
    #[must_use]
    pub const fn runtime(&self) -> Option<&tokio::runtime::Handle> {
        self.runtime.as_ref()
    }

    /// Sets the Tokio runtime this `Bind` spawns its tasks onto, overriding the global runtime.
    /// `None` returns it to the global runtime.
    ///
    /// This takes effect from the next request; a task already in flight stays on the runtime it
    /// was spawned on. The same requirements as for [`set_global_runtime`] apply.
    ///
    /// Native only: on WASM, tasks always run on the browser's event loop.
    #[cfg(not(target_family = "wasm"))]
    pub fn set_runtime(&mut self, handle: Option<tokio::runtime::Handle>) {
        self.runtime = handle;
    }

    /// Returns whether finished data is retained across undrawn frames.
    #[must_use]
    pub const fn retain(&self) -> bool {
        self.config.contains(ConfigFlags::RETAIN)
    }

    /// Sets retain policy for finished data.
    pub fn set_retain(&mut self, retain: bool) {
        if retain {
            self.config.insert(ConfigFlags::RETAIN);
        } else {
            self.config.remove(ConfigFlags::RETAIN);
        }
    }

    /// Returns whether background tasks are physically aborted when cleared or replaced.
    #[must_use]
    pub const fn abort_on_clear(&self) -> bool {
        self.config.contains(ConfigFlags::ABORT)
    }

    /// Sets whether background tasks are physically aborted when cleared or replaced.
    ///
    /// See [`ConfigFlags::ABORT`] for how this behaves on native and WASM targets.
    pub fn set_abort(&mut self, abort: bool) {
        if abort {
            self.config.insert(ConfigFlags::ABORT);
        } else {
            self.config.remove(ConfigFlags::ABORT);
        }
    }

    /// Internal async function that awaits the user's future and sends the result back.
    async fn req_inner<F>(fut: F, tx: oneshot::Sender<Result<T, E>>)
    where
        F: Future<Output = Result<T, E>> + 'static,
        T: MaybeSend,
    {
        let result = fut.await;
        if matches!(tx.send(result), Ok(())) {
            // If the send was successful, request a repaint to show the new data.
            request_repaint();
        } else {
            // This occurs if the `Bind` was dropped before the future completed.
            warn!("Future result was dropped because the receiver was gone.");
        }
    }

    /// Starts an asynchronous operation if the `Bind` is not already `Pending`.
    ///
    /// The provided future `f` is spawned onto the appropriate runtime (`tokio` for native,
    /// `wasm-bindgen-futures` for WASM). The `Bind` state transitions to `Pending`.
    ///
    /// This method calls `poll()` internally.
    pub fn request<Fut>(&mut self, f: Fut)
    where
        Fut: Future<Output = Result<T, E>> + MaybeSend + 'static,
        T: MaybeSend,
        E: MaybeSend,
    {
        // Drive state machine to catch results from tasks finishing this frame
        self.poll();

        // Handle existing task based on config; sets state to Idle if still Pending
        self.abort();

        self.last_start_time = CURR_FRAME.load(std::sync::atomic::Ordering::Relaxed);
        let (tx, rx) = oneshot::channel();

        // Spawn the async task
        tracing::trace!("spawning async request #{}", self.times_executed + 1);

        #[cfg(not(target_family = "wasm"))]
        let in_flight = {
            let runtime = self.runtime.as_ref().unwrap_or_else(|| global_runtime());
            InFlight {
                recv: rx,
                handle: runtime.spawn(Self::req_inner(f, tx)).abort_handle(),
            }
        };

        #[cfg(target_family = "wasm")]
        let in_flight = {
            let (abort_tx, abort_rx) = oneshot::channel();
            wasm_bindgen_futures::spawn_local(abortable(Self::req_inner(f, tx), abort_rx));
            InFlight { recv: rx, abort_tx }
        };

        self.in_flight = Some(in_flight);
        self.state = State::Pending;
        self.times_executed += 1;
    }

    /// Convenience: periodic request using `std::time::Duration`.
    #[must_use]
    pub fn request_every<Fut>(&mut self, f: impl FnOnce() -> Fut, every: std::time::Duration) -> f64
    where
        Fut: Future<Output = Result<T, E>> + MaybeSend + 'static,
        T: MaybeSend,
        E: MaybeSend,
    {
        self.request_every_sec(f, every.as_secs_f64())
    }

    /// Requests an operation to run periodically.
    ///
    /// If the `Bind` is not `Pending` and more than `secs` seconds have passed since the
    /// last completion, a new request is started by calling `f`.
    ///
    /// # Returns
    /// The time in seconds remaining until the next scheduled refresh. A negative value
    /// indicates a refresh is overdue.
    pub fn request_every_sec<Fut>(&mut self, f: impl FnOnce() -> Fut, secs: f64) -> f64
    where
        Fut: Future<Output = Result<T, E>> + MaybeSend + 'static,
        T: MaybeSend,
        E: MaybeSend,
    {
        let state = self.get_state();
        let since_completed = self.since_completed_raw();

        if state != State::Pending && since_completed > secs {
            self.request(f());
        }

        secs - since_completed
    }

    /// Explicitly cancels the in-flight task and resets the state to `Idle`.
    ///
    /// If the [`ConfigFlags::ABORT`] flag is set, the background task is physically
    /// terminated: aborted on native, or dropped at its next poll on WASM. Otherwise, the
    /// task runs to completion and its result is simply ignored.
    pub fn abort(&mut self) {
        // Logical: Take the in-flight handle. This detaches the Bind from the task.
        if let Some(task) = self.in_flight.take() {
            // Physical: Only signal the runtime to kill the task if configured.
            if self.config.contains(ConfigFlags::ABORT) {
                task.abort();
            }
        }

        // Ensure state is synchronized with the removal of the in-flight task.
        if matches!(self.state, State::Pending) {
            self.state = State::Idle;
        }
    }

    /// Clears any existing data and immediately starts a new async operation.
    ///
    /// If an operation was `Pending`, its result will be discarded. The background task runs to
    /// completion unless the [`ConfigFlags::ABORT`] flag is set.
    ///
    /// This is a convenience method equivalent to calling `clear()` followed by `request()`.
    pub fn refresh<Fut>(&mut self, f: Fut)
    where
        Fut: Future<Output = Result<T, E>> + MaybeSend + 'static,
        T: MaybeSend,
        E: MaybeSend,
    {
        self.clear();
        self.request(f);
    }

    /// Takes ownership of the result if the operation is `Finished`.
    ///
    /// If the state is `Finished`, this method returns `Some(result)`, consumes the data
    /// internally, and resets the state to `Idle`. If the state is not `Finished`,
    /// it returns `None`.
    ///
    /// This method calls `poll()` internally.
    pub fn take(&mut self) -> Option<Result<T, E>> {
        self.poll();

        if matches!(self.state, State::Finished) {
            assert!(
                self.data.is_some(),
                "State was Finished but data was None. This indicates a bug."
            );
            self.state = State::Idle;
            self.data.take()
        } else {
            None
        }
    }

    /// Manually sets the data and moves the state to `Finished`.
    ///
    /// This can be used to inject data into the `Bind` without running an async operation.
    ///
    /// If an operation is currently `Pending`, it will be aborted. If data is already
    /// present, it will be overwritten.
    pub fn fill(&mut self, data: Result<T, E>) {
        if self.just_completed() || self.just_started() {
            tracing::warn!(
                "Bind::fill called multiple times in the same frame. This may indicate a logic error in your update loop."
            );
        }

        // Ensure clean state: abort pending tasks and reset to Idle.
        self.clear();

        self.state = State::Finished;

        let now = CURR_FRAME.load(std::sync::atomic::Ordering::Relaxed);
        self.last_start_time = now;
        self.last_complete_time = now;

        self.data = Some(data);
    }

    /// Returns `Some(&T)` when finished successfully.
    #[must_use]
    pub fn ok_ref(&mut self) -> Option<&T> {
        self.poll();
        self.data.as_ref()?.as_ref().ok()
    }

    /// Returns `Some(&E)` when finished with error.
    #[must_use]
    pub fn err_ref(&mut self) -> Option<&E> {
        self.poll();
        self.data.as_ref()?.as_ref().err()
    }

    /// Takes and returns `T` only if finished successfully.
    pub fn take_ok(&mut self) -> Option<T> {
        self.poll();
        match self.data.take()? {
            Ok(t) => {
                self.state = State::Idle;
                Some(t)
            }
            Err(e) => {
                self.data = Some(Err(e));
                None
            }
        }
    }

    /// Checks if the current state is `Idle`.
    /// This method calls `poll()` internally.
    pub fn is_idle(&mut self) -> bool {
        self.poll();
        matches!(self.state, State::Idle)
    }

    /// Checks if the current state is `Pending`.
    /// This method calls `poll()` internally.
    pub fn is_pending(&mut self) -> bool {
        self.poll();
        matches!(self.state, State::Pending)
    }

    /// Checks if the current state is `Finished`.
    /// This method calls `poll()` internally.
    pub fn is_finished(&mut self) -> bool {
        self.poll();
        matches!(self.state, State::Finished)
    }

    /// Returns `true` if finished with `Ok`.
    #[must_use]
    pub fn is_ok(&mut self) -> bool {
        self.poll();
        matches!(self.data, Some(Ok(_)))
    }

    /// Returns `true` if finished with `Err`.
    #[must_use]
    pub fn is_err(&mut self) -> bool {
        self.poll();
        matches!(self.data, Some(Err(_)))
    }

    /// Returns `true` if the operation finished during the current `egui` frame.
    /// This method calls `poll()` internally.
    #[allow(clippy::float_cmp)]
    pub fn just_completed(&mut self) -> bool {
        self.poll();
        self.last_complete_time == CURR_FRAME.load(std::sync::atomic::Ordering::Relaxed)
    }

    /// If the operation just completed this frame, invokes the provided closure with
    /// a reference to the result.
    pub fn on_finished(&mut self, f: impl FnOnce(&Result<T, E>)) {
        if self.just_completed()
            && let Some(ref d) = self.data
        {
            f(d);
        }
    }

    /// Returns `true` if the operation started during the current `egui` frame.
    /// This method calls `poll()` internally.
    #[allow(clippy::float_cmp)]
    pub fn just_started(&mut self) -> bool {
        self.poll();
        self.last_start_time == CURR_FRAME.load(std::sync::atomic::Ordering::Relaxed)
    }

    /// Gets the `egui` time when the operation started.
    /// This method calls `poll()` internally.
    pub fn get_start_time(&mut self) -> f64 {
        self.poll();
        self.last_start_time
    }

    /// Gets the `egui` time when the operation completed.
    /// This method calls `poll()` internally.
    pub fn get_complete_time(&mut self) -> f64 {
        self.poll();
        self.last_complete_time
    }

    /// Gets the duration between the start and completion of the operation.
    /// This method calls `poll()` internally.
    pub fn get_elapsed(&mut self) -> f64 {
        self.poll();
        self.last_complete_time - self.last_start_time
    }

    /// Gets the time elapsed since the operation started.
    /// This method calls `poll()` internally.
    pub fn since_started(&mut self) -> f64 {
        self.poll();
        CURR_FRAME.load(std::sync::atomic::Ordering::Relaxed) - self.last_start_time
    }

    /// Gets the time elapsed since the operation completed.
    /// This method calls `poll()` internally.
    pub fn since_completed(&mut self) -> f64 {
        self.poll();
        self.since_completed_raw()
    }
    fn since_completed_raw(&self) -> f64 {
        CURR_FRAME.load(std::sync::atomic::Ordering::Relaxed) - self.last_complete_time
    }

    /// Returns an immutable reference to the stored data, if any.
    /// This method calls `poll()` internally.
    pub fn read(&mut self) -> &Option<Result<T, E>> {
        self.poll();
        &self.data
    }
    /// Returns an immutable reference in the ref pattern to the stored data, if any.
    /// This method calls `poll()` internally.
    pub fn read_as_ref(&mut self) -> Option<Result<&T, &E>> {
        self.poll();
        self.data.as_ref().map(Result::as_ref)
    }

    /// Returns a mutable reference to the stored data, if any.
    /// This method calls `poll()` internally.
    pub fn read_mut(&mut self) -> &mut Option<Result<T, E>> {
        self.poll();
        &mut self.data
    }
    /// Returns a mutable reference in the ref pattern to the stored data, if any.
    /// This method calls `poll()` internally.
    pub fn read_as_mut(&mut self) -> Option<Result<&mut T, &mut E>> {
        self.poll();
        self.data.as_mut().map(Result::as_mut)
    }

    /// Returns the current `State` of the binding.
    /// This method calls `poll()` internally.
    pub fn get_state(&mut self) -> State {
        self.poll();
        self.state
    }

    /// Returns the ref filled state of the `Bind`, allowing for exhaustive pattern matching.
    ///
    /// This is often the most ergonomic way to display UI based on the `Bind`'s state.
    /// This method calls `poll()` internally.
    /// Invariant: `State::Finished` implies `data.is_some()`.
    ///
    /// # Example
    /// ```ignore
    /// match my_bind.state() {
    ///     StateWithData::Idle => { /* ... */ }
    ///     StateWithData::Pending => { ui.spinner(); }
    ///     StateWithData::Finished(data) => { ui.label(format!("Data: {data:?}")); }
    ///     StateWithData::Failed(err) => { ui.label(format!("Error: {err:?}")); }
    /// }
    /// ```
    pub fn state(&mut self) -> StateWithData<'_, T, E> {
        self.poll();
        match self.state {
            State::Idle => StateWithData::Idle,
            State::Pending => StateWithData::Pending,
            State::Finished => match self.data.as_ref() {
                Some(Ok(data)) => StateWithData::Finished(data),
                Some(Err(err)) => StateWithData::Failed(err),
                None => {
                    // This case should be unreachable due to internal invariants.
                    // If state is Finished, data must be Some.
                    self.state = State::Idle;
                    StateWithData::Idle
                }
            },
        }
    }

    /// Returns the ref filled state or starts a new request if idle.
    ///
    /// This method is an ergonomic way to drive a UI. If the `Bind` is `Idle` and has no
    /// data, it immediately calls the provided closure `f` to start an async operation,
    /// transitioning the state to `Pending`.
    ///
    /// In all cases, it returns the current `StateWithData` for immediate use in a `match`
    /// statement, making it easy to display a loading indicator, the finished data, or an error.
    ///
    /// # Example
    /// ```ignore
    /// // In your UI update function:
    /// match my_bind.state_or_request(fetch_data) {
    ///     StateWithData::Idle => { /* This branch is typically not reached on the first call */ }
    ///     StateWithData::Pending => { ui.spinner(); }
    ///     StateWithData::Finished(data) => { ui.label(format!("Data: {:?}", data)); }
    ///     StateWithData::Failed(err) => { ui.label(format!("Error: {:?}", err)); }
    /// }
    /// ```
    pub fn state_or_request<Fut>(&mut self, f: impl FnOnce() -> Fut) -> StateWithData<'_, T, E>
    where
        Fut: Future<Output = Result<T, E>> + MaybeSend + 'static,
        T: MaybeSend,
        E: MaybeSend,
    {
        self.poll();

        if self.data.is_none() && matches!(self.state, State::Idle) {
            self.request(f());
        }
        self.state()
    }

    /// Clears any stored data and resets the state to `Idle`.
    ///
    /// If an operation was `Pending`, its result will be discarded. The background task runs to
    /// completion unless the [`ConfigFlags::ABORT`] flag is set.
    ///
    /// This method calls `poll()` internally.
    pub fn clear(&mut self) {
        self.poll();
        self.abort();
        self.state = State::Idle;
        self.data = None;
    }

    /// Returns a reference to the data, or starts a new request if idle.
    ///
    /// If data is already available (`Finished`), it returns a reference to it.
    /// If the state is `Idle` and no data is present, it calls `f` to start a new async
    /// operation and returns `None`.
    /// If `Pending`, it returns `None`.
    ///
    /// This method calls `poll()` internally.
    pub fn read_or_request<Fut>(&mut self, f: impl FnOnce() -> Fut) -> Option<&Result<T, E>>
    where
        Fut: Future<Output = Result<T, E>> + MaybeSend + 'static,
        T: MaybeSend,
        E: MaybeSend,
    {
        self.poll();

        if self.data.is_none() && matches!(self.state, State::Idle) {
            self.request(f());
        }
        self.data.as_ref()
    }

    /// Returns a mutable reference to the data, or starts a new request if idle.
    ///
    /// This is the mutable version of `read_or_request`.
    ///
    /// This method calls `poll()` internally.
    pub fn read_mut_or_request<Fut>(&mut self, f: impl FnOnce() -> Fut) -> Option<&mut Result<T, E>>
    where
        Fut: Future<Output = Result<T, E>> + MaybeSend + 'static,
        T: MaybeSend,
        E: MaybeSend,
    {
        self.poll();

        if self.data.is_none() && matches!(self.state, State::Idle) {
            self.request(f());
        }
        self.data.as_mut()
    }

    /// Drives the state machine. This should be called once per frame before accessing state.
    ///
    /// **Note**: Most other methods on `Bind` call this internally, so you usually don't
    /// need to call it yourself.
    ///
    /// This method performs several key actions:
    /// 1. Checks if a pending future has completed and, if so, updates the state to `Finished`.
    /// 2. Updates internal frame timers used for `retain` logic and time tracking.
    /// 3. If `retain` is `false`, it clears the data if the `Bind` was not polled in the previous frame.
    ///
    /// # Panics
    /// - Panics if the state is `Pending` but the internal receiver is missing. This indicates a bug in `egui-async`.
    /// - Panics if the `oneshot` channel's sender is dropped without sending a value, which would mean the
    ///   spawned task terminated unexpectedly.
    pub fn poll(&mut self) {
        let curr_frame = CURR_FRAME.load(std::sync::atomic::Ordering::Relaxed);

        // Avoid re-polling within the same frame.
        #[allow(clippy::float_cmp)]
        if curr_frame == self.drawn_time_last {
            return;
        }

        // Shift frame times for tracking visibility across frames.
        self.drawn_time_prev = self.drawn_time_last;
        self.drawn_time_last = curr_frame;

        // If `retain` is false and the UI element associated with this `Bind` was not rendered
        // in the previous frame, we clear its data to free resources and ensure a fresh load.
        if !self.retain() && !self.was_drawn_last_frame() {
            // Manually clear state to avoid a recursive call to poll() from clear().
            self.abort();
            self.state = State::Idle;
            self.data = None;
        }

        if matches!(self.state, State::Pending) {
            let task = self
                .in_flight
                .as_mut()
                .expect("BUG: Pending but no in_flight.");
            match task.poll_result() {
                Ok(result) => {
                    self.data = Some(result);
                    self.last_complete_time = CURR_FRAME.load(std::sync::atomic::Ordering::Relaxed);
                    self.state = State::Finished;
                    self.in_flight = None; // Drop the in_flight receiver as it's no longer needed.
                }
                Err(oneshot::error::TryRecvError::Empty) => {
                    // Future is still running, do nothing.
                }
                Err(oneshot::error::TryRecvError::Closed) => {
                    // Treat as cancellation: clear the pending state without crashing the app.
                    tracing::warn!(
                        "Async task cancelled: sender dropped without sending a result."
                    );
                    self.state = State::Idle;
                    self.in_flight = None;
                }
            }
        }
    }

    /// Checks if this `Bind` has been polled during the current `egui` frame.
    #[allow(clippy::float_cmp)]
    pub fn was_drawn_this_frame(&self) -> bool {
        self.drawn_time_last == CURR_FRAME.load(std::sync::atomic::Ordering::Relaxed)
    }

    /// Checks if this `Bind` was polled during the previous `egui` frame.
    ///
    /// This is used internally to implement the `retain` logic.
    #[allow(clippy::float_cmp)]
    pub fn was_drawn_last_frame(&self) -> bool {
        self.drawn_time_prev == LAST_FRAME.load(std::sync::atomic::Ordering::Relaxed)
    }

    /// Returns the total number of times an async operation has been executed.
    pub const fn count_executed(&self) -> usize {
        self.times_executed
    }
}