Skip to main content

gpui/
asset_cache.rs

1use crate::{App, EntityId, SharedString, SharedUri, Task};
2use collections::FxHashSet;
3use futures::{Future, TryFutureExt};
4
5use std::cell::RefCell;
6use std::fmt::Debug;
7use std::hash::{BuildHasher, Hash};
8use std::marker::PhantomData;
9use std::mem;
10use std::path::{Path, PathBuf};
11use std::rc::Rc;
12use std::sync::Arc;
13
14pub(crate) struct CachedLoad<T> {
15    state: Rc<RefCell<CachedLoadState<T>>>,
16    // Keep the owner outside the state so publishing a result cannot cancel its own task.
17    _task: Task<()>,
18}
19
20enum CachedLoadState<T> {
21    Loading(FxHashSet<EntityId>),
22    Loaded(T),
23}
24
25impl<T: Clone + Send + 'static> CachedLoad<T> {
26    pub(crate) fn new(future: impl Future<Output = T> + Send + 'static, cx: &App) -> Self {
27        let state = Rc::new(RefCell::new(CachedLoadState::Loading(FxHashSet::default())));
28        let task = cx.background_executor().spawn(future);
29        let task = cx.spawn({
30            let state = Rc::downgrade(&state);
31            async move |cx| {
32                let result = task.await;
33                let Some(state) = state.upgrade() else {
34                    return;
35                };
36                let previous =
37                    mem::replace(&mut *state.borrow_mut(), CachedLoadState::Loaded(result));
38                let CachedLoadState::Loading(views) = previous else {
39                    unreachable!("a cached load completes only once");
40                };
41                cx.update(|cx| {
42                    for view in views {
43                        cx.notify(view);
44                    }
45                });
46            }
47        });
48        Self { state, _task: task }
49    }
50
51    /// vue-native fork: an entry that is already loaded with `value`
52    /// ([`App::replace_asset`]).
53    pub(crate) fn ready(value: T) -> Self {
54        Self {
55            state: Rc::new(RefCell::new(CachedLoadState::Loaded(value))),
56            _task: Task::ready(()),
57        }
58    }
59
60    /// vue-native fork: has the load finished?
61    pub(crate) fn is_loaded(&self) -> bool {
62        matches!(&*self.state.borrow(), CachedLoadState::Loaded(_))
63    }
64
65    pub(crate) fn get(&self) -> Option<T> {
66        match &*self.state.borrow() {
67            CachedLoadState::Loading(_) => None,
68            CachedLoadState::Loaded(result) => Some(result.clone()),
69        }
70    }
71
72    pub(crate) fn use_by(&self, view: EntityId) -> Option<T> {
73        match &mut *self.state.borrow_mut() {
74            CachedLoadState::Loading(views) => {
75                views.insert(view);
76                None
77            }
78            CachedLoadState::Loaded(result) => Some(result.clone()),
79        }
80    }
81}
82
83/// An enum representing
84#[derive(Debug, PartialEq, Eq, Hash, Clone)]
85pub enum Resource {
86    /// This resource is at a given URI
87    Uri(SharedUri),
88    /// This resource is at a given path in the file system
89    Path(Arc<Path>),
90    /// This resource is embedded in the application binary
91    Embedded(SharedString),
92}
93
94impl From<SharedUri> for Resource {
95    fn from(value: SharedUri) -> Self {
96        Self::Uri(value)
97    }
98}
99
100impl From<PathBuf> for Resource {
101    fn from(value: PathBuf) -> Self {
102        Self::Path(value.into())
103    }
104}
105
106impl From<Arc<Path>> for Resource {
107    fn from(value: Arc<Path>) -> Self {
108        Self::Path(value)
109    }
110}
111
112/// A trait for asynchronous asset loading.
113pub trait Asset: 'static {
114    /// The source of the asset.
115    type Source: Clone + Hash + Send;
116
117    /// The loaded asset
118    type Output: Clone + Send;
119
120    /// Load the asset asynchronously
121    fn load(
122        source: Self::Source,
123        cx: &mut App,
124    ) -> impl Future<Output = Self::Output> + Send + 'static;
125}
126
127/// An asset Loader which logs the [`Err`] variant of a [`Result`] during loading
128pub enum AssetLogger<T> {
129    #[doc(hidden)]
130    _Phantom(PhantomData<T>, &'static dyn crate::seal::Sealed),
131}
132
133impl<T, R, E> Asset for AssetLogger<T>
134where
135    T: Asset<Output = Result<R, E>>,
136    R: Clone + Send,
137    E: Clone + Send + Debug,
138{
139    type Source = T::Source;
140
141    type Output = T::Output;
142
143    fn load(
144        source: Self::Source,
145        cx: &mut App,
146    ) -> impl Future<Output = Self::Output> + Send + 'static {
147        let load = T::load(source, cx);
148        load.inspect_err(|e| log::error!("Failed to load asset: {:?}", e))
149    }
150}
151
152/// Use a quick, non-cryptographically secure hash function to get an identifier from data
153pub fn hash<T: Hash>(data: &T) -> u64 {
154    collections::FxBuildHasher.hash_one(data)
155}
156
157#[cfg(test)]
158mod tests {
159    use super::*;
160    use crate::{AppContext, TestAppContext};
161    use futures::channel::oneshot;
162    use std::{
163        cell::Cell,
164        collections::VecDeque,
165        hash::{Hash, Hasher},
166        rc::Rc,
167        sync::{
168            Arc, Mutex,
169            atomic::{AtomicUsize, Ordering},
170        },
171    };
172
173    #[gpui::test]
174    fn cached_load_caches_success_and_error(cx: &mut TestAppContext) {
175        let successful_load =
176            cx.update(|cx| CachedLoad::new(async { Ok::<_, &'static str>(42) }, cx));
177        let failed_load =
178            cx.update(|cx| CachedLoad::new(async { Err::<i32, _>("load failed") }, cx));
179
180        assert_eq!(successful_load.get(), None);
181        assert_eq!(failed_load.get(), None);
182
183        cx.run_until_parked();
184
185        assert_eq!(successful_load.get(), Some(Ok(42)));
186        assert_eq!(successful_load.get(), Some(Ok(42)));
187        assert_eq!(failed_load.get(), Some(Err("load failed")));
188        assert_eq!(failed_load.get(), Some(Err("load failed")));
189    }
190
191    #[gpui::test]
192    fn completed_load_without_subscribers_is_cached_and_deduplicated(cx: &mut TestAppContext) {
193        let (sender, receiver) = oneshot::channel();
194        let source = TestAssetSource::new(1, [receiver]);
195
196        assert_eq!(cx.update(|cx| cx.fetch_asset::<TestAsset>(&source)), None);
197        assert_eq!(cx.update(|cx| cx.fetch_asset::<TestAsset>(&source)), None);
198        assert_eq!(source.load_count(), 1);
199
200        assert!(sender.send(Ok(42)).is_ok());
201        cx.run_until_parked();
202
203        assert_eq!(
204            cx.update(|cx| cx.fetch_asset::<TestAsset>(&source)),
205            Some(Ok(42))
206        );
207        assert_eq!(
208            cx.update(|cx| cx.fetch_asset::<TestAsset>(&source)),
209            Some(Ok(42))
210        );
211        assert_eq!(source.load_count(), 1);
212    }
213
214    #[gpui::test]
215    fn load_completion_notifies_each_observing_entity_once(cx: &mut TestAppContext) {
216        let (sender, receiver) = oneshot::channel::<i32>();
217        let load = cx.update(|cx| {
218            CachedLoad::new(
219                async move { receiver.await.expect("test sends a result") },
220                cx,
221            )
222        });
223        let first_notification_count = Rc::new(Cell::new(0));
224        let second_notification_count = Rc::new(Cell::new(0));
225        let (first_entity, second_entity) = cx.update(|cx| {
226            let first_entity = cx.new(|_| ());
227            let second_entity = cx.new(|_| ());
228            cx.observe(&first_entity, {
229                let first_notification_count = first_notification_count.clone();
230                move |_, _| first_notification_count.set(first_notification_count.get() + 1)
231            })
232            .detach();
233            cx.observe(&second_entity, {
234                let second_notification_count = second_notification_count.clone();
235                move |_, _| second_notification_count.set(second_notification_count.get() + 1)
236            })
237            .detach();
238            (first_entity, second_entity)
239        });
240
241        assert_eq!(load.use_by(first_entity.entity_id()), None);
242        assert_eq!(load.use_by(first_entity.entity_id()), None);
243        assert_eq!(load.use_by(second_entity.entity_id()), None);
244
245        assert!(sender.send(42).is_ok());
246        cx.run_until_parked();
247
248        assert_eq!(first_notification_count.get(), 1);
249        assert_eq!(second_notification_count.get(), 1);
250        assert_eq!(load.use_by(first_entity.entity_id()), Some(42));
251        assert_eq!(load.use_by(second_entity.entity_id()), Some(42));
252    }
253
254    #[gpui::test]
255    fn removing_pending_asset_cancels_it_and_replacement_ignores_stale_completion(
256        cx: &mut TestAppContext,
257    ) {
258        let (stale_sender, stale_receiver) = oneshot::channel();
259        let (replacement_sender, replacement_receiver) = oneshot::channel();
260        let source = TestAssetSource::new(2, [stale_receiver, replacement_receiver]);
261
262        assert_eq!(cx.update(|cx| cx.fetch_asset::<TestAsset>(&source)), None);
263        assert_eq!(source.load_count(), 1);
264        cx.run_until_parked();
265
266        cx.update(|cx| cx.remove_asset::<TestAsset>(&source));
267        assert!(!cx.update(|cx| cx.has_asset::<TestAsset>(&source)));
268        cx.run_until_parked();
269        assert!(stale_sender.send(Ok(1)).is_err());
270
271        assert_eq!(cx.update(|cx| cx.fetch_asset::<TestAsset>(&source)), None);
272        assert_eq!(source.load_count(), 2);
273
274        assert!(replacement_sender.send(Err("replacement failed")).is_ok());
275        cx.run_until_parked();
276
277        assert_eq!(
278            cx.update(|cx| cx.fetch_asset::<TestAsset>(&source)),
279            Some(Err("replacement failed"))
280        );
281        assert_eq!(source.load_count(), 2);
282    }
283
284    #[gpui::test]
285    fn eviction_after_worker_completion_does_not_publish_into_replacement(cx: &mut TestAppContext) {
286        let (sender, receiver) = oneshot::channel();
287        let (replacement_sender, replacement_receiver) = oneshot::channel();
288        let source = TestAssetSource::new(3, [receiver, replacement_receiver]);
289
290        assert_eq!(cx.update(|cx| cx.fetch_asset::<TestAsset>(&source)), None);
291        assert!(sender.send(Ok(1)).is_ok());
292        while source.completion_count.load(Ordering::SeqCst) == 0 {
293            assert!(cx.background_executor.tick());
294        }
295        assert_eq!(cx.update(|cx| cx.fetch_asset::<TestAsset>(&source)), None);
296
297        cx.update(|cx| {
298            cx.remove_asset::<TestAsset>(&source);
299            assert_eq!(cx.fetch_asset::<TestAsset>(&source), None);
300        });
301        cx.run_until_parked();
302        assert_eq!(cx.update(|cx| cx.fetch_asset::<TestAsset>(&source)), None);
303
304        assert!(replacement_sender.send(Ok(2)).is_ok());
305        cx.run_until_parked();
306        assert_eq!(
307            cx.update(|cx| cx.fetch_asset::<TestAsset>(&source)),
308            Some(Ok(2))
309        );
310        assert_eq!(source.load_count(), 2);
311    }
312
313    struct TestAsset;
314
315    #[derive(Clone)]
316    struct TestAssetSource {
317        id: usize,
318        load_count: Arc<AtomicUsize>,
319        completion_count: Arc<AtomicUsize>,
320        receivers: Arc<Mutex<VecDeque<oneshot::Receiver<Result<i32, &'static str>>>>>,
321    }
322
323    impl TestAssetSource {
324        fn new(
325            id: usize,
326            receivers: impl IntoIterator<Item = oneshot::Receiver<Result<i32, &'static str>>>,
327        ) -> Self {
328            Self {
329                id,
330                load_count: Arc::new(AtomicUsize::new(0)),
331                completion_count: Arc::new(AtomicUsize::new(0)),
332                receivers: Arc::new(Mutex::new(receivers.into_iter().collect())),
333            }
334        }
335
336        fn load_count(&self) -> usize {
337            self.load_count.load(Ordering::SeqCst)
338        }
339    }
340
341    impl Hash for TestAssetSource {
342        fn hash<H: Hasher>(&self, state: &mut H) {
343            self.id.hash(state);
344        }
345    }
346
347    impl Asset for TestAsset {
348        type Source = TestAssetSource;
349        type Output = Result<i32, &'static str>;
350
351        fn load(
352            source: Self::Source,
353            _cx: &mut App,
354        ) -> impl Future<Output = Self::Output> + Send + 'static {
355            source.load_count.fetch_add(1, Ordering::SeqCst);
356            let receiver = source
357                .receivers
358                .lock()
359                .expect("test receiver mutex should not be poisoned")
360                .pop_front()
361                .expect("each test load should have a receiver");
362            async move {
363                let result = match receiver.await {
364                    Ok(result) => result,
365                    Err(_) => Err("cancelled"),
366                };
367                source.completion_count.fetch_add(1, Ordering::SeqCst);
368                result
369            }
370        }
371    }
372}