GitCorner

Code

ossartcraftlightcraft🌐
5a24289898fd
//! Preparing photos in the background (PERF-PREVIEW-PREP, notes 47 and 48): while the user culls,
//! the photos ahead are made ready before they are reached, and with the machine otherwise idle
//! the previews of every photo in view are built, so stepping never waits for a render.
//!
//! What is prepared is set per mode, because each mode needs something else:
//! - **Culling** (a folder browsed before import, the Import tab): previews of every photo in the
//!   folder, the next photos' loupe renders and their eye focus strips.
//! - **Library**: the same for the photos in the library's view.
//! - **Develop** (editing): the next photos decoded and kept ready to edit.
//!
//! Each mode has its own switch for the whole-view build, how many photos ahead to prepare (0 =
//! none) and which photos ([`Scope`]). The settings are app-wide (the desktop app keeps them in `ui.json`)
//! and a library can keep its own (its `prefs.json`): a timelapse library prepares nothing while a
//! wedding library prepares everything.
//!
//! The whole-view build is the preview build ([`crate::cmd::previews`]) in its background form: two
//! lanes, waiting whenever the photo on screen is being made ([`foreground`]), nearest photos to the
//! user first and re-aimed as they move ([`crate::cmd::previews::PreviewBuild::focus_on`]), photos
//! with previews skipped, one row in the activity stack that can be cancelled. It starts once the
//! user is culling (a few photos stepped through in the loupe), never just because a library was
//! opened (note 36: opening an old library to look at two photos must not start rebuilding).

use std::sync::Arc;
use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};

use lightcraft_catalog::PhotoId;
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};

use crate::Session;
use crate::cmd::previews::PreviewBuild;

/// Which photos a mode prepares.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum Scope {
    /// Every photo in view (the folder, the collection, the filter).
    #[default]
    All,
    /// Only picks, and photos with stars or a colour label.
    Marked,
    /// Only the photo on screen: nothing ahead, nothing in the background.
    OnScreen,
}

impl Scope {
    pub fn parse(s: &str) -> Option<Scope> {
        match s {
            "all" => Some(Scope::All),
            "marked" => Some(Scope::Marked),
            "onScreen" => Some(Scope::OnScreen),
            _ => None,
        }
    }
}

/// The most photos prepared ahead of the one on screen.
pub const MAX_AHEAD: u8 = 20;

/// What one mode prepares.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct ModePrep {
    /// Build the previews of every photo in scope in the background.
    pub previews: bool,
    /// Photos ahead (in the direction of travel) whose loupe render is made before they are reached (0 = none).
    pub ahead: u8,
    /// Photos ahead whose eye focus strip is worked out before they are reached (0 = only the one on
    /// screen), for a frontend that shows one (the desktop app doesn't yet).
    pub eye_ahead: u8,
    pub scope: Scope,
}

impl Default for ModePrep {
    fn default() -> Self {
        ModePrep { previews: true, ahead: 5, eye_ahead: 8, scope: Scope::All }
    }
}

/// Editing: what is kept ready for the next photos.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct DevelopPrep {
    /// Photos ahead decoded and kept ready to edit (0 = none).
    pub ahead: u8,
    pub scope: Scope,
}

impl Default for DevelopPrep {
    fn default() -> Self {
        DevelopPrep { ahead: 2, scope: Scope::All }
    }
}

/// The background preparation settings.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct PrepSettings {
    pub culling: ModePrep,
    pub library: ModePrep,
    pub develop: DevelopPrep,
}

impl PrepSettings {
    /// Values from files or agents kept in range.
    pub fn sanitized(mut self) -> Self {
        for m in [&mut self.culling, &mut self.library] {
            m.ahead = m.ahead.min(MAX_AHEAD);
            m.eye_ahead = m.eye_ahead.min(MAX_AHEAD);
        }
        self.develop.ahead = self.develop.ahead.min(MAX_AHEAD);
        self
    }

    /// The settings of a browsing mode ([`Mode::Culling`] or [`Mode::Library`]; Develop prepares
    /// views the way the Library does).
    pub fn mode(&self, mode: Mode) -> ModePrep {
        match mode {
            Mode::Culling => self.culling,
            Mode::Library | Mode::Develop => self.library,
        }
    }

    /// Photos ahead to render for the loupe in `mode` (0 when its scope is the photo on screen).
    pub fn ahead(&self, mode: Mode) -> usize {
        match mode {
            Mode::Develop if self.develop.scope == Scope::OnScreen => 0,
            Mode::Develop => usize::from(self.develop.ahead),
            m => {
                let p = self.mode(m);
                if p.scope == Scope::OnScreen { 0 } else { usize::from(p.ahead) }
            }
        }
    }

    /// Photos ahead whose eye focus strip is worked out in `mode`.
    pub fn eye_ahead(&self, mode: Mode) -> usize {
        let p = self.mode(mode);
        if p.scope == Scope::OnScreen { 0 } else { usize::from(p.eye_ahead) }
    }

    /// The scope that applies in `mode`.
    pub fn scope(&self, mode: Mode) -> Scope {
        match mode {
            Mode::Develop => self.develop.scope,
            m => self.mode(m).scope,
        }
    }

    /// Apply the fields of `patch` (a partial object, as `prefs.setBackgroundPrep` takes it).
    pub fn patched(&self, patch: &Value) -> Result<PrepSettings, String> {
        let mut v = serde_json::to_value(self).map_err(|e| e.to_string())?;
        merge(&mut v, patch, 0);
        let p: PrepSettings = serde_json::from_value(v).map_err(|e| format!("background preparation settings: {e}"))?;
        Ok(p.sanitized())
    }
}

/// `patch` merged into `into`, objects field by field (two levels deep: mode → field).
fn merge(into: &mut Value, patch: &Value, depth: usize) {
    match (into, patch) {
        (Value::Object(a), Value::Object(b)) if depth < 3 => {
            for (k, v) in b {
                match a.get_mut(k) {
                    Some(old) => merge(old, v, depth + 1),
                    None => {
                        a.insert(k.clone(), v.clone());
                    }
                }
            }
        }
        (a, b) => *a = b.clone(),
    }
}

/// What the user is doing, as far as preparation goes.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum Mode {
    Culling,
    Library,
    Develop,
}

impl Mode {
    pub fn parse(s: &str) -> Option<Mode> {
        match s {
            "culling" => Some(Mode::Culling),
            "library" => Some(Mode::Library),
            "develop" => Some(Mode::Develop),
            _ => None,
        }
    }

    /// The mode of what `s` shows when the frontend doesn't say: a folder browsed before import is
    /// culling, anything else the library.
    pub fn of(s: &Session) -> Mode {
        if s.source == crate::LibrarySource::Folder { Mode::Culling } else { Mode::Library }
    }
}

/// Photos the user steps through in the loupe before the whole view is prepared: a library opened
/// to look at one photo starts nothing.
pub const STEPS_BEFORE_BUILD: usize = 3;
/// How long a view whose build couldn't start waits before trying again.
pub const RETRY_AFTER: std::time::Duration = std::time::Duration::from_secs(30);

/// The background preparation's state in a session.
#[derive(Default)]
pub struct PrepState {
    /// App-wide settings.
    pub app: PrepSettings,
    /// This library's own (`None`: it uses the app-wide ones).
    pub library: Option<PrepSettings>,
    /// The background build this preparation started.
    build: Option<Arc<PreviewBuild>>,
    /// The view (its signature) whose build was started, or that the user stopped.
    started_for: Option<u64>,
    declined_for: Option<u64>,
    /// A build that couldn't start: the view (its signature), and when it may try again (not on
    /// every tick while the cause lasts; CodeRabbit on #3080).
    pub retry_at: Option<(u64, web_time::Instant)>,
    /// Tests: the next starts to fail, as a build thread that can't be spawned does.
    #[cfg(test)]
    pub(crate) fail_starts: usize,
    /// The view the steps were counted in, the photo last seen, and the steps.
    steps_in: Option<u64>,
    last_at: Option<PhotoId>,
    steps: usize,
}

impl std::fmt::Debug for PrepState {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("PrepState").field("app", &self.app).field("library", &self.library).field("steps", &self.steps).finish()
    }
}

impl PrepState {
    /// The settings in use.
    pub fn settings(&self) -> PrepSettings {
        self.library.unwrap_or(self.app)
    }
}

/// Until when (ms on [`clock_ms`]) the photo on screen is being made: background work waits.
static FOREGROUND_UNTIL: AtomicU64 = AtomicU64::new(0);

/// How long a foreground signal holds background work back (ms): a little more than a frame
/// apart, so a frontend saying it every frame holds it back the whole time.
const FOREGROUND_HOLD_MS: u64 = 250;

fn clock_ms() -> u64 {
    static START: std::sync::OnceLock<web_time::Instant> = std::sync::OnceLock::new();
    u64::try_from(START.get_or_init(web_time::Instant::now).elapsed().as_millis()).unwrap_or(u64::MAX)
}

/// The frontend says the photo on screen is being made (a render it waits for is on its way):
/// background preparation waits until it has been quiet for a moment.
pub fn foreground() {
    FOREGROUND_UNTIL.store(clock_ms().saturating_add(FOREGROUND_HOLD_MS), Ordering::Relaxed);
}

/// Whether the photo on screen is being made now.
pub fn foreground_busy() -> bool {
    #[cfg(test)]
    if TEST_HOLD.load(Ordering::Relaxed) > 0 {
        return true;
    }
    clock_ms() < FOREGROUND_UNTIL.load(Ordering::Relaxed)
}

/// Tests: hold every background build at its foreground wait until released (a synchronization
/// point that doesn't depend on the hold's 250 ms). A count, not a switch: tests running side by
/// side each hold until their own release, and one test's release doesn't free another's build.
#[cfg(test)]
static TEST_HOLD: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0);

/// Holds background builds while it lives (also when the test fails), whatever other holds do.
#[cfg(test)]
pub(crate) struct TestHold;

#[cfg(test)]
impl TestHold {
    pub(crate) fn new() -> Self {
        TEST_HOLD.fetch_add(1, Ordering::Relaxed);
        TestHold
    }
}

#[cfg(test)]
impl Drop for TestHold {
    fn drop(&mut self) {
        // (one release per hold made: never below 0)
        TEST_HOLD.fetch_sub(1, Ordering::Relaxed);
    }
}

/// Wait while the photo on screen is being made. `true`: `cancel` was set meanwhile.
pub fn wait_for_foreground(cancel: &AtomicBool) -> bool {
    #[cfg(not(target_arch = "wasm32"))]
    while foreground_busy() {
        if cancel.load(Ordering::Relaxed) {
            return true;
        }
        std::thread::sleep(std::time::Duration::from_millis(30));
    }
    cancel.load(Ordering::Relaxed)
}

/// Photos the background build renders side by side: each render spreads over the cores already,
/// so two keep the machine busy while leaving room for the photo on screen.
pub fn background_lanes() -> usize {
    let cores = std::thread::available_parallelism().map_or(2, |n| n.get());
    if cores >= 8 { 2 } else { 1 }
}

/// A cheap identity of the photos a build prepares: a build is started once per view. `scope`
/// [`Scope::Marked`]: which of them are marked counts too (marking a photo changes the set).
fn signature(ids: &[PhotoId], s: &Session, scope: Scope) -> u64 {
    let mut h = lightcraft_preview::Hasher128::new();
    h.u64(ids.len() as u64).u64(s.catalog.len() as u64);
    // every id: a sort that moves photos in the middle is another view
    for id in ids {
        h.u64(id.0);
        if scope == Scope::Marked {
            h.u64(u64::from(marked(s, *id)));
        }
    }
    h.finish().0 as u64
}

/// Whether `id` is a pick, or has stars or a colour label (the [`Scope::Marked`] photos).
pub fn marked(s: &Session, id: PhotoId) -> bool {
    s.catalog.photo(id).is_some_and(|p| p.flag == lightcraft_catalog::Flag::Pick || p.rating > 0 || p.label.is_some())
}

impl Session {
    /// How long until a view whose build couldn't start tries again ([`RETRY_AFTER`]), while one
    /// waits: the app asks for a frame then, so the retry doesn't wait for the next input
    /// (CodeRabbit on #3077/#3080). `None` once the time has come.
    pub fn prep_retry_in(&self) -> Option<std::time::Duration> {
        // (a deadline that has passed asks for nothing: the pass at it tried again, or the view
        // can't be tried now and a frame at once on every pass would keep an idle window drawing:
        // CodeRabbit on #3077 / #3080)
        let wait = self.prep.retry_at.map(|(_, at)| at.saturating_duration_since(web_time::Instant::now()))?;
        (!wait.is_zero()).then_some(wait)
    }

    /// The background preparation settings in use (this library's own, else the app-wide ones).
    pub fn prep_settings(&self) -> PrepSettings {
        self.prep.settings()
    }

    /// Advance the background preparation (cheap; call every frame). `mode`: what the user is doing;
    /// `at`: the photo in the loupe (`None` in the grid), `backward`: stepping back.
    pub fn prep_tick(&mut self, mode: Mode, at: Option<PhotoId>, backward: bool) {
        let settings = self.prep.settings();
        let want = settings.mode(mode);
        // the whole view's build follows its own row (Culling, or Library also while editing): its
        // switch and its "which photos"; the Editing row's scope is for the photos kept ready ahead
        let wanted = want.previews && want.scope != Scope::OnScreen;
        // the running build: re-aimed at the user, stopped when switched off
        if let Some(b) = self.prep.build.clone() {
            if b.running() {
                if !wanted {
                    b.cancel.store(true, Ordering::Relaxed);
                } else if self.prep.started_for.is_some_and(|sig| sig != signature(&self.visible_cloned(), self, want.scope)) {
                    // another view (a folder, a filter, another library): this build's photos are
                    // not the ones shown; stopped, and the view now shown is prepared in its place
                    // (not counted as stopped by the user)
                    b.cancel.store(true, Ordering::Relaxed);
                    self.prep.started_for = None;
                } else if let Some(id) = at {
                    b.focus_on(id, backward);
                }
                return;
            }
            self.prep.build = None;
            let mine = self.preview_build.as_ref().is_some_and(|p| Arc::ptr_eq(p, &b));
            if b.cancel.load(Ordering::Relaxed) {
                if mine && wanted {
                    // stopped from its row: not again for this view
                    self.prep.declined_for = self.prep.started_for;
                } else {
                    // replaced by a build that was asked for, or switched off: may start again later
                    self.prep.started_for = None;
                }
            }
        }
        if !wanted {
            return;
        }
        let Some(at) = at else { return };
        let ids = self.visible_cloned();
        let sig = signature(&ids, self, want.scope);
        if self.prep.steps_in != Some(sig) {
            self.prep.steps_in = Some(sig);
            self.prep.steps = 0;
            self.prep.last_at = None;
        }
        if self.prep.last_at != Some(at) {
            self.prep.last_at = Some(at);
            self.prep.steps = self.prep.steps.saturating_add(1);
        }
        let busy = self.preview_build.as_ref().is_some_and(|b| b.running());
        if busy
            || self.prep.steps < STEPS_BEFORE_BUILD
            || self.prep.started_for == Some(sig)
            || self.prep.declined_for == Some(sig)
            || self.prep.retry_at.is_some_and(|(view, at)| view == sig && web_time::Instant::now() < at)
            || self.library.as_ref().is_none_or(|l| !l.on_disk)
        {
            return;
        }
        let ids: Vec<u64> = match want.scope {
            Scope::Marked => ids.into_iter().filter(|id| marked(self, *id)).map(|id| id.0).collect(),
            _ => ids.into_iter().map(|id| id.0).collect(),
        };
        self.prep.started_for = Some(sig);
        if ids.is_empty() {
            return;
        }
        let p = json!({"ids": ids, "background": true, "from": at.0, "backward": backward});
        // (tests: a start made to fail, as a build thread that can't be spawned fails)
        #[cfg(test)]
        let fail = self.prep.fail_starts.checked_sub(1).map(|left| self.prep.fail_starts = left).is_some();
        #[cfg(not(test))]
        let fail = false;
        let started = if fail {
            Err(crate::EngineError::Disabled("library.buildPreviews".into(), "test: the build couldn't start".into()))
        } else {
            self.execute("library.buildPreviews", &p)
        };
        match started {
            Ok(_) => {
                self.prep.build = self.preview_build.clone();
                self.prep.retry_at = None;
            }
            Err(e) => {
                // not started: this view tries again after a while (not on every tick)
                self.prep.started_for = None;
                self.prep.retry_at = web_time::Instant::now().checked_add(RETRY_AFTER).map(|at| (sig, at));
                log::info!("background preparation: {e}");
            }
        }
    }

    /// Change the background preparation settings: the app-wide ones, or (`library`) this library's
    /// own. Saved at once.
    pub fn set_prep_settings(&mut self, settings: PrepSettings, library: bool) -> crate::Result<()> {
        let settings = settings.sanitized();
        if library {
            let previous = self.prep.library;
            self.prep.library = Some(settings);
            self.save_library_prep(previous)
        } else {
            let previous = self.prep.app;
            self.prep.app = settings;
            let saved = self.save_prefs();
            if saved.is_err() {
                self.prep.app = previous;
            }
            saved
        }
    }

    /// Back to the app-wide settings for this library.
    pub fn clear_library_prep(&mut self) -> crate::Result<()> {
        let previous = self.prep.library;
        self.prep.library = None;
        self.save_library_prep(previous)
    }

    /// Save this library's preparation settings; when that fails, `previous` is put back, so the
    /// session doesn't go on with settings the command reported as not changed (CodeRabbit on #3544).
    fn save_library_prep(&mut self, previous: Option<PrepSettings>) -> crate::Result<()> {
        let saved = self.save_prefs();
        if saved.is_err() {
            self.prep.library = previous;
        }
        saved
    }

    pub(crate) fn prep_json(&self) -> Value {
        json!({
            "app": self.prep.app,
            "library": self.prep.library,
            "settings": self.prep.settings(),
            "own": self.prep.library.is_some(),
            "building": self.prep.build.as_ref().filter(|b| b.running()).map(|b| b.json()),
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn a_patch_changes_only_what_it_names_and_is_kept_in_range() {
        let p = PrepSettings::default().patched(&json!({"culling": {"ahead": 99}, "develop": {"scope": "onScreen"}})).unwrap();
        assert_eq!(p.culling.ahead, MAX_AHEAD);
        assert_eq!(p.culling.eye_ahead, 8, "untouched");
        assert!(p.library.previews);
        assert_eq!(p.develop.scope, Scope::OnScreen);
        assert_eq!(p.ahead(Mode::Develop), 0);
        assert!(PrepSettings::default().patched(&json!({"culling": {"scope": "sometimes"}})).is_err());
    }

    /// Tests side by side: one test's release doesn't free the build another test holds (CodeRabbit on #3077).
    #[test]
    fn one_tests_release_does_not_free_another_tests_hold() {
        let a = TestHold::new();
        let b = TestHold::new();
        drop(a);
        assert!(TEST_HOLD.load(Ordering::Relaxed) > 0 && foreground_busy(), "the other hold still holds");
        drop(b);
    }

    #[test]
    fn the_photo_on_screen_holds_background_work_back() {
        let cancel = AtomicBool::new(false);
        foreground();
        assert!(foreground_busy());
        let t = web_time::Instant::now();
        assert!(!wait_for_foreground(&cancel));
        assert!(t.elapsed().as_millis() >= 100, "waited for the foreground to go quiet");
        cancel.store(true, Ordering::Relaxed);
        foreground();
        assert!(wait_for_foreground(&cancel), "a cancel ends the wait");
    }
}