Struct Bind 

pub struct Bind<T, E> { /* private fields */ }

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).

Implementations

impl<T: 'static, E: 'static> Bind<T, E>

pub const fn new(retain: bool) -> Self

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.

pub fn request<Fut>(&mut self, f: Fut)

where Fut: Future<Output = Result<T, E>> + MaybeSend + 'static, T: MaybeSend, E: MaybeSend,

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_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,

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 refresh<Fut>(&mut self, f: Fut)

where Fut: Future<Output = Result<T, E>> + MaybeSend + 'static, T: MaybeSend, E: MaybeSend,

Clears any existing data and immediately starts a new async operation.

If an operation was Pending, its result will be discarded. The background task is not cancelled and will run to completion.

This is a convenience method equivalent to calling clear() followed by request().

pub fn take(&mut self) -> Option<Result<T, E>>

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 fill(&mut self, data: Result<T, E>)

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.

Panics

Panics if the current state is not Idle.

pub fn is_idle(&mut self) -> bool

Checks if the current state is Idle. This method calls poll() internally.

pub fn is_pending(&mut self) -> bool

Checks if the current state is Pending. This method calls poll() internally.

pub fn is_finished(&mut self) -> bool

Checks if the current state is Finished. This method calls poll() internally.

pub fn just_completed(&mut self) -> bool

Returns true if the operation finished during the current egui frame. This method calls poll() internally.

pub fn on_finished(&mut self, f: impl FnOnce(&Result<T, E>))

If the operation just completed this frame, invokes the provided closure with a reference to the result.

pub fn just_started(&mut self) -> bool

Returns true if the operation started during the current egui frame. This method calls poll() internally.

pub fn get_start_time(&mut self) -> f64

Gets the egui time when the operation started. This method calls poll() internally.

pub fn get_complete_time(&mut self) -> f64

Gets the egui time when the operation completed. This method calls poll() internally.

pub fn get_elapsed(&mut self) -> f64

Gets the duration between the start and completion of the operation. This method calls poll() internally.

pub fn since_started(&mut self) -> f64

Gets the time elapsed since the operation started. This method calls poll() internally.

pub fn since_completed(&mut self) -> f64

Gets the time elapsed since the operation completed. This method calls poll() internally.

pub fn read(&mut self) -> &Option<Result<T, E>>

Returns an immutable reference to the stored data, if any. This method calls poll() internally.

pub fn read_as_ref(&mut self) -> Option<Result<&T, &E>>

Returns an immutable reference in the ref pattern to the stored data, if any. This method calls poll() internally.

pub fn read_mut(&mut self) -> &mut Option<Result<T, E>>

Returns a mutable reference to the stored data, if any. This method calls poll() internally.

pub fn read_as_mut(&mut self) -> Option<Result<&mut T, &mut E>>

Returns a mutable reference in the ref pattern to the stored data, if any. This method calls poll() internally.

pub fn get_state(&mut self) -> State

Returns the current State of the binding. This method calls poll() internally.

pub fn state(&mut self) -> StateWithData<'_, T, E>

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.

Example

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_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,

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

// 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 clear(&mut self)

Clears any stored data and resets the state to Idle.

If an operation was Pending, its result will be discarded. The background task is not cancelled and will run to completion.

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,

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_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,

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 poll(&mut self)

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 was_drawn_this_frame(&self) -> bool

Checks if this Bind has been polled during the current egui frame.

pub fn was_drawn_last_frame(&self) -> bool

Checks if this Bind was polled during the previous egui frame.

This is used internally to implement the retain logic.

pub const fn count_executed(&self) -> usize

Returns the total number of times an async operation has been executed.

impl<T: 'static, E: Debug + 'static> Bind<T, E>

pub fn read_or_error<Fut>( &mut self, f: impl FnOnce() -> Fut, ui: &mut Ui, ) -> Option<&T>

where Fut: Future<Output = Result<T, E>> + MaybeSend + 'static, T: MaybeSend, E: MaybeSend,

Reads the data if available, otherwise shows an error popup if there was an error. If there was an error, the popup will have a “Retry” button that will trigger the given future. If the data is not available, returns None. This does NOT automatically request the data if it is not available.

pub fn read_mut_or_error<Fut>( &mut self, f: impl FnOnce() -> Fut, ui: &mut Ui, ) -> Option<&mut T>

where Fut: Future<Output = Result<T, E>> + MaybeSend + 'static, T: MaybeSend, E: MaybeSend,

Reads the data mutably if available, otherwise shows an error popup if there was an error. If there was an error, the popup will have a “Retry” button that will trigger the given future. If the data is not available, returns None. This does NOT automatically request the data if it is not available.

pub fn read_or_request_or_error<Fut>( &mut self, f: impl FnOnce() -> Fut, ui: &mut Ui, ) -> Option<&T>

where Fut: Future<Output = Result<T, E>> + MaybeSend + 'static, T: MaybeSend, E: MaybeSend,

Reads the data if available, otherwise requests it using the given future. If there was an error, the popup will have a “Retry” button that will trigger the given future. If the data is not available, returns None. This automatically requests the data if it is not available.

pub fn read_mut_or_request_or_error<Fut>( &mut self, f: impl FnOnce() -> Fut, ui: &mut Ui, ) -> Option<&mut T>

where Fut: Future<Output = Result<T, E>> + MaybeSend + 'static, T: MaybeSend, E: MaybeSend,

Reads the data mutably if available, otherwise requests it using the given future. If there was an error, the popup will have a “Retry” button that will trigger the given future. If the data is not available, returns None. This automatically requests the data if it is not available.

Trait Implementations

impl<T, E> Debug for Bind<T, E>

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

Formats the value using the given formatter.

impl<T: 'static, E: 'static> Default for Bind<T, E>

fn default() -> Self

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.