lurq 0.65.1

A Rust UI toolkit with typed components, retained state, reactive signals, GPU rendering, and DevTools.
Documentation
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
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
//! The cache of decoded images: one entry per content key and size cap,
//! loading, ready or failed, within a byte budget.

use std::{
  collections::HashMap,
  sync::{
    Arc,
    atomic::{AtomicU64, Ordering},
  },
  time::Duration,
};

use parking_lot::{Condvar, Mutex};

use super::{ImageDecodeError, ImageKey, ImageLoadState, ImageSizeCap, ImageSource, decode_image, worker::Workers};
use crate::{app::window::WindowWaker, images::ImageData};

/// Decoded RGBA the cache keeps at most, before the least recently used
/// ready images are dropped from it (an image a node still shows is kept by
/// that node).
pub const DEFAULT_BUDGET_BYTES: usize = 128 * 1024 * 1024;

const WORKER_COUNT: usize = 2;

type CacheKey = (ImageKey, Option<ImageSizeCap>);

struct Entry {
  state: ImageLoadState,
  /// The RGBA bytes of a `Ready` state; 0 otherwise. `Inner::used` is their
  /// sum over the entries.
  bytes: usize,
  last_used: u64,
  /// Windows to wake when the decode ends, one per window.
  wakers: Vec<WindowWaker>,
}

struct Inner {
  entries: HashMap<CacheKey, Entry>,
  /// Decode jobs submitted and not finished: each job calls `finish` once.
  pending: usize,
  budget: usize,
  used: usize,
  clock: u64,
}

/// A decode that must end its entry even when the decoder panics: the entry
/// would stay `Loading` forever, with `pending` never counted down.
struct FinishOnDrop {
  shared: Arc<Shared>,
  cache_key: CacheKey,
  result: Option<Result<ImageData, ImageDecodeError>>,
}

impl Drop for FinishOnDrop {
  fn drop(&mut self) {
    // Without a result the job did not run to its end: the decoder
    // panicked, or no worker took the job (the workers are gone).
    let result = self.result.take().unwrap_or_else(|| {
      let said = "the image decode did not run: the decoder panicked or no worker took the job";
      Err(ImageDecodeError::new(
        said,
        crate::core::PictureError::Other(Arc::from(said)),
      ))
    });
    self.shared.finish(self.cache_key, result);
  }
}

/// A cache of decoded images with its own decode workers. The runtime uses
/// the process-wide one, [`decoded_images`](super::decoded_images); a test
/// may make one of its own.
pub struct DecodedImages {
  shared: Arc<Shared>,
}

struct Shared {
  inner: Mutex<Inner>,
  idle: Condvar,
  workers: Workers,
  /// Counts finished decodes, so a tree can tell that something it waits
  /// for ended.
  completed: AtomicU64,
}

impl Default for DecodedImages {
  fn default() -> Self {
    Self::new()
  }
}

impl DecodedImages {
  /// An empty cache with the default budget and its own worker threads.
  pub fn new() -> Self {
    Self {
      shared: Arc::new(Shared {
        inner: Mutex::new(Inner {
          entries: HashMap::new(),
          pending: 0,
          budget: DEFAULT_BUDGET_BYTES,
          used: 0,
          clock: 0,
        }),
        idle: Condvar::new(),
        workers: Workers::new(WORKER_COUNT),
        completed: AtomicU64::new(0),
      }),
    }
  }

  /// The image under `key` decoded within `cap`: its state now. An unknown
  /// key starts a decode of `source()` on a worker and is `Loading`; `wake`
  /// is called when that decode ends, so the window draws the image. A
  /// second request for the same key joins the first.
  pub fn load(
    &self,
    key: ImageKey,
    cap: Option<ImageSizeCap>,
    source: impl FnOnce() -> ImageSource,
    wake: Option<WindowWaker>,
  ) -> ImageLoadState {
    #[cfg(target_arch = "wasm32")]
    return self.load_in_browser(key, cap, source, wake);
    #[cfg(not(target_arch = "wasm32"))]
    self.load_with(key, cap, wake, || {
      let source = source();
      move || decode_image(&source, cap)
    })
  }

  /// [`load`](Self::load) in a browser: the browser decodes what it can off the page's thread (`web_decode`), and
  /// the rest is decoded as on a desktop, on the page's thread after this turn of the loop.
  #[cfg(target_arch = "wasm32")]
  fn load_in_browser(
    &self,
    key: ImageKey,
    cap: Option<ImageSizeCap>,
    source: impl FnOnce() -> ImageSource,
    wake: Option<WindowWaker>,
  ) -> ImageLoadState {
    let mut finish = match self.begin(key, cap, wake) {
      Ok(finish) => finish,
      Err(state) => return state,
    };
    let source = source();
    wasm_bindgen_futures::spawn_local(async move {
      let decoded = match &source {
        ImageSource::Bytes(bytes) if super::browser_decodes(bytes) => super::web_decode::decode(bytes, cap).await,
        _ => None,
      };
      finish.result = Some(match decoded {
        Some(decoded) => Ok(decoded),
        None => decode_image(&source, cap),
      });
      drop(finish);
    });
    ImageLoadState::Loading
  }

  /// [`load`](Self::load) with the decode given as a job: `decode()` builds
  /// it on the caller's thread (taking the source), the job runs on a worker.
  pub(super) fn load_with<J>(
    &self,
    key: ImageKey,
    cap: Option<ImageSizeCap>,
    wake: Option<WindowWaker>,
    decode: impl FnOnce() -> J,
  ) -> ImageLoadState
  where
    J: FnOnce() -> Result<ImageData, ImageDecodeError> + Send + 'static,
  {
    let mut finish = match self.begin(key, cap, wake) {
      Ok(finish) => finish,
      Err(state) => return state,
    };
    let job = decode();
    // A job the workers do not take is dropped with its guard, which fails
    // the entry: one finish either way.
    self.shared.workers.submit(move || {
      finish.result = Some(job());
      drop(finish);
    });
    ImageLoadState::Loading
  }

  /// The state of the entry under `key` and `cap` where there is one (`Err`), joined by `wake`; or a new entry,
  /// loading, and the guard that finishes it (`Ok`).
  fn begin(
    &self,
    key: ImageKey,
    cap: Option<ImageSizeCap>,
    wake: Option<WindowWaker>,
  ) -> Result<FinishOnDrop, ImageLoadState> {
    let cache_key = (key, cap);
    let mut inner = self.shared.inner.lock();
    inner.clock += 1;
    let clock = inner.clock;
    if let Some(entry) = inner.entries.get_mut(&cache_key) {
      entry.last_used = clock;
      if let (ImageLoadState::Loading, Some(wake)) = (&entry.state, wake)
        && !entry.wakers.iter().any(|known| Arc::ptr_eq(known, &wake))
      {
        entry.wakers.push(wake);
      }
      return Err(entry.state.clone());
    }
    inner.entries.insert(
      cache_key,
      Entry {
        state: ImageLoadState::Loading,
        bytes: 0,
        last_used: clock,
        wakers: wake.into_iter().collect(),
      },
    );
    inner.pending += 1;
    drop(inner);
    Ok(FinishOnDrop {
      shared: Arc::clone(&self.shared),
      cache_key,
      result: None,
    })
  }

  /// A cache whose workers are gone: every decode fails without running.
  #[cfg(test)]
  pub(super) fn without_workers() -> Self {
    Self {
      shared: Arc::new(Shared {
        inner: Mutex::new(Inner {
          entries: HashMap::new(),
          pending: 0,
          budget: DEFAULT_BUDGET_BYTES,
          used: 0,
          clock: 0,
        }),
        idle: Condvar::new(),
        workers: Workers::closed(),
        completed: AtomicU64::new(0),
      }),
    }
  }

  /// The state of the image under `key` and `cap`, without starting a decode.
  pub fn state(&self, key: ImageKey, cap: Option<ImageSizeCap>) -> Option<ImageLoadState> {
    self
      .shared
      .inner
      .lock()
      .entries
      .get(&(key, cap))
      .map(|entry| entry.state.clone())
  }

  /// Puts an image the app decoded itself under `key`, so nodes that ask for
  /// it find it ready. A decode of the same key still running finishes
  /// without replacing it; windows waiting for that decode are woken now.
  /// Like a finished decode, an inserted image larger than the whole budget
  /// is kept until the next eviction.
  pub fn insert(&self, key: ImageKey, cap: Option<ImageSizeCap>, data: ImageData) {
    let bytes = rgba_bytes(&data);
    let wakers = {
      let mut inner = self.shared.inner.lock();
      inner.clock += 1;
      let last_used = inner.clock;
      let mut wakers = Vec::new();
      if let Some(old) = inner.entries.insert(
        (key, cap),
        Entry {
          state: ImageLoadState::Ready(data),
          bytes,
          last_used,
          wakers: Vec::new(),
        },
      ) {
        inner.used -= old.bytes;
        wakers = old.wakers;
      }
      inner.used += bytes;
      evict(&mut inner, Some((key, cap)));
      wakers
    };
    for wake in wakers {
      wake();
    }
  }

  /// Forgets the image under `key` and `cap` that is ready or failed, so that the next request for it decodes
  /// again: a way to try a failed one again, once what made it fail may have passed. `true` where there was
  /// one to forget. A decode still running is left to end. Every tree walks for its loading images in its next
  /// pass, so a node that showed the error asks again without being built again.
  pub fn forget(&self, key: ImageKey, cap: Option<ImageSizeCap>) -> bool {
    let forgotten = {
      let mut inner = self.shared.inner.lock();
      match inner.entries.get(&(key, cap)) {
        Some(entry) if !entry.state.is_loading() => {
          let bytes = entry.bytes;
          inner.entries.remove(&(key, cap));
          inner.used -= bytes;
          true
        }
        _ => false,
      }
    };
    if forgotten {
      crate::app::runtime::note_loading_image_built();
    }
    forgotten
  }

  /// Decodes still running.
  pub fn pending(&self) -> usize {
    self.shared.inner.lock().pending
  }

  /// How many decodes have ended since the cache was made.
  pub fn completed(&self) -> u64 {
    self.shared.completed.load(Ordering::Acquire)
  }

  /// Blocks until no decode is pending, or `timeout` passes (`false`).
  ///
  /// A browser's one thread cannot wait for itself: there this only tells
  /// whether a decode is pending now.
  #[cfg(not(target_arch = "wasm32"))]
  pub fn wait_idle(&self, timeout: Duration) -> bool {
    let deadline = std::time::Instant::now() + timeout;
    let mut inner = self.shared.inner.lock();
    while inner.pending > 0 {
      if self.shared.idle.wait_until(&mut inner, deadline).timed_out() {
        return inner.pending == 0;
      }
    }
    true
  }

  #[cfg(target_arch = "wasm32")]
  pub fn wait_idle(&self, _timeout: Duration) -> bool {
    self.pending() == 0
  }

  /// The decoded RGBA kept at most; see [`DEFAULT_BUDGET_BYTES`].
  pub fn budget(&self) -> usize {
    self.shared.inner.lock().budget
  }

  pub fn set_budget(&self, bytes: usize) {
    let mut inner = self.shared.inner.lock();
    inner.budget = bytes;
    evict(&mut inner, None);
  }

  /// The decoded RGBA the cache holds now.
  pub fn used_bytes(&self) -> usize {
    self.shared.inner.lock().used
  }

  /// Drops every ready and failed entry; running decodes finish and stay.
  pub fn clear(&self) {
    let mut inner = self.shared.inner.lock();
    inner.entries.retain(|_, entry| entry.state.is_loading());
    inner.used = 0;
  }
}

impl Shared {
  /// Ends one decode job: its entry takes the result while it still waits
  /// for it. An entry that `insert` filled meanwhile, or one evicted or
  /// cleared, keeps what it has and the result is dropped. Counts the job
  /// down either way, once its windows are woken, so `wait_idle` returns
  /// after the wakes. The finished entry is the most recently used and is
  /// never the one evicted to make room for itself: an image larger than
  /// the whole budget is kept and shown, and leaves the cache at the next
  /// eviction (the node showing it keeps its pixels).
  fn finish(&self, cache_key: CacheKey, result: Result<ImageData, ImageDecodeError>) {
    let wakers = {
      let mut inner = self.inner.lock();
      inner.clock += 1;
      let clock = inner.clock;
      match inner.entries.get_mut(&cache_key) {
        Some(entry) if entry.state.is_loading() => {
          let bytes = result.as_ref().map(rgba_bytes).unwrap_or(0);
          entry.bytes = bytes;
          entry.last_used = clock;
          entry.state = match result {
            Ok(data) => ImageLoadState::Ready(data),
            Err(error) => ImageLoadState::Failed(Arc::new(error)),
          };
          let wakers = std::mem::take(&mut entry.wakers);
          inner.used += bytes;
          evict(&mut inner, Some(cache_key));
          wakers
        }
        _ => Vec::new(),
      }
    };
    for wake in wakers {
      wake();
    }
    let mut inner = self.inner.lock();
    inner.pending = inner.pending.saturating_sub(1);
    self.completed.fetch_add(1, Ordering::AcqRel);
    self.idle.notify_all();
  }
}

/// Drops the least recently used ready images until the budget holds,
/// never `keep`.
fn evict(inner: &mut Inner, keep: Option<CacheKey>) {
  while inner.used > inner.budget {
    let victim = inner
      .entries
      .iter()
      .filter(|(key, entry)| Some(**key) != keep && matches!(entry.state, ImageLoadState::Ready(_)))
      .min_by_key(|(_, entry)| entry.last_used)
      .map(|(key, _)| *key);
    let Some(victim) = victim else {
      return;
    };
    if let Some(entry) = inner.entries.remove(&victim) {
      inner.used -= entry.bytes;
    }
  }
}

fn rgba_bytes(data: &ImageData) -> usize {
  (data.width() as usize) * (data.height() as usize) * 4
}