Skip to main content

use_future

Function use_future 

Source
pub fn use_future<'s, D, T, F>(
    cx: &mut Cx<'s, '_>,
    deps: D,
    f: impl FnOnce() -> F,
) -> &'s Poll<T>
where D: Hash, T: Send + 'static, F: SpawnFuture<T>,
Expand description

Run the future f builds, and report where it has got to.

f is called at the call site whenever the hash of deps changes (and on the first visit), so it can read locals and State guards while it builds the future. The future itself is 'static, so it has to own what it needs.

The result lands on the visit after the future finished; finishing asks for a repaint, so that visit happens without the user touching anything. Changing deps builds a new future and drops whatever the old one eventually returns; it does not stop the old one, because a future cannot be stopped.

Like use_memo the reference borrows the store rather than the Cx, so it can be read next to a State guard. A child component waits with a let-else, which is where React would throw:

#[component]
fn Body(cx: &mut Cx, url: &str) {
    let text = use_future(cx, url, || load(url.to_owned()));
    let Poll::Ready(text) = text else { return };
    cx.ui().label(text.clone());
}

While the hook is Pending it counts towards the nearest <Suspense> boundary, which draws its fallback instead of its children.