This is unreleased documentation for Yew Next version.
For up-to-date documentation, see the latest version on docs.rs.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
use std::cell::RefCell;
use std::future::Future;
use std::pin::Pin;
use std::rc::Rc;
use std::sync::atomic::{AtomicBool, Ordering};
use std::task::{Context, Poll};

use thiserror::Error;

use crate::platform::spawn_local;
use crate::Callback;

thread_local! {
    static SUSPENSION_ID: RefCell<usize> = RefCell::default();
}

/// A Suspension.
///
/// This type can be sent back as an `Err(_)` to suspend a component until the underlying task
/// completes.
#[derive(Error, Debug, Clone)]
#[error("suspend component rendering")]
pub struct Suspension {
    id: usize,
    listeners: Rc<RefCell<Vec<Callback<Self>>>>,

    resumed: Rc<AtomicBool>,
}

impl PartialEq for Suspension {
    fn eq(&self, rhs: &Self) -> bool {
        self.id == rhs.id
    }
}

impl Suspension {
    /// Creates a Suspension.
    pub fn new() -> (Self, SuspensionHandle) {
        let id = SUSPENSION_ID.with(|m| {
            let mut m = m.borrow_mut();
            *m += 1;

            *m
        });

        let self_ = Suspension {
            id,
            listeners: Rc::default(),
            resumed: Rc::default(),
        };

        (self_.clone(), SuspensionHandle { inner: self_ })
    }

    /// Returns `true` if the current suspension is already resumed.
    pub fn resumed(&self) -> bool {
        self.resumed.load(Ordering::Relaxed)
    }

    /// Creates a Suspension that resumes when the [`Future`] resolves.
    pub fn from_future(f: impl Future<Output = ()> + 'static) -> Self {
        let (self_, handle) = Self::new();

        spawn_local(async move {
            f.await;
            handle.resume();
        });

        self_
    }

    /// Listens to a suspension and get notified when it resumes.
    pub(crate) fn listen(&self, cb: Callback<Self>) {
        if self.resumed() {
            cb.emit(self.clone());
            return;
        }

        let mut listeners = self.listeners.borrow_mut();

        listeners.push(cb);
    }

    fn resume_by_ref(&self) {
        // The component can resume rendering by returning a non-suspended result after a state is
        // updated, so we always need to check here.
        if !self.resumed() {
            self.resumed.store(true, Ordering::Relaxed);
            let listeners = self.listeners.borrow();

            for listener in listeners.iter() {
                listener.emit(self.clone());
            }
        }
    }
}

impl Future for Suspension {
    type Output = ();

    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
        if self.resumed() {
            return Poll::Ready(());
        }

        let waker = cx.waker().clone();
        self.listen(Callback::from(move |_| {
            waker.wake_by_ref();
        }));

        Poll::Pending
    }
}

/// A Suspension Result.
pub type SuspensionResult<T> = std::result::Result<T, Suspension>;

/// A Suspension Handle.
///
/// This type is used to control the corresponding [`Suspension`].
///
/// When the current struct is dropped or `resume` is called, it will resume rendering of current
/// component.
#[derive(Debug, PartialEq)]
pub struct SuspensionHandle {
    inner: Suspension,
}

impl SuspensionHandle {
    /// Resumes component rendering.
    pub fn resume(self) {
        self.inner.resume_by_ref();
    }
}

impl Drop for SuspensionHandle {
    fn drop(&mut self) {
        self.inner.resume_by_ref();
    }
}