cranpose_services/
background.rs

1//! Background execution: ask the OS to keep running briefly after the app is
2//! backgrounded, so in-flight work (e.g. draining a recognition queue) can
3//! finish instead of being suspended immediately.
4//!
5//! The platform backend installs an implementation via
6//! [`set_platform_background_activity`] (iOS `beginBackgroundTask`, Android a
7//! foreground service). No default: [`background_activity`] returns `None` where
8//! unsupported, and the app simply runs only while foregrounded.
9
10use std::sync::atomic::{AtomicUsize, Ordering};
11use std::sync::Arc;
12use std::sync::Mutex;
13use std::sync::OnceLock;
14
15/// Marks periods of important work so the platform grants background running
16/// time. Implementations are `Send + Sync` (the app toggles activity from its
17/// worker threads).
18pub trait BackgroundActivity: Send + Sync {
19    /// `true` when important work starts, `false` when it finishes. Calls are
20    /// balanced by the app but implementations must tolerate repeats.
21    fn set_active(&self, active: bool);
22}
23
24pub type BackgroundActivityRef = Arc<dyn BackgroundActivity>;
25
26fn slot() -> &'static Mutex<Option<BackgroundActivityRef>> {
27    static SLOT: OnceLock<Mutex<Option<BackgroundActivityRef>>> = OnceLock::new();
28    SLOT.get_or_init(|| Mutex::new(None))
29}
30
31/// Installs the platform background-activity handler, replacing any previous one.
32pub fn set_platform_background_activity(activity: BackgroundActivityRef) {
33    if background_active() {
34        activity.set_active(true);
35    }
36    if let Ok(mut s) = slot().lock() {
37        *s = Some(activity);
38    }
39}
40
41/// Removes any registered handler (tests/teardown).
42pub fn clear_platform_background_activity() {
43    if let Ok(mut s) = slot().lock() {
44        *s = None;
45    }
46}
47
48/// The registered background-activity handler, or `None` where unsupported.
49pub fn background_activity() -> Option<BackgroundActivityRef> {
50    slot().lock().ok().and_then(|s| s.clone())
51}
52
53static ACTIVE_LEASES: AtomicUsize = AtomicUsize::new(0);
54
55/// A claim that important work needs the host's background execution allowance.
56/// The allowance remains active until every outstanding lease is dropped.
57pub struct BackgroundWorkLease {
58    active: bool,
59}
60
61impl Drop for BackgroundWorkLease {
62    fn drop(&mut self) {
63        if !self.active {
64            return;
65        }
66        self.active = false;
67        if ACTIVE_LEASES.fetch_sub(1, Ordering::AcqRel) == 1 {
68            if let Some(activity) = background_activity() {
69                activity.set_active(false);
70            }
71        }
72    }
73}
74
75/// Acquires background execution for one independent operation.
76pub fn acquire_background_work() -> BackgroundWorkLease {
77    if ACTIVE_LEASES.fetch_add(1, Ordering::AcqRel) == 0 {
78        if let Some(activity) = background_activity() {
79            activity.set_active(true);
80        }
81    }
82    BackgroundWorkLease { active: true }
83}
84
85/// Whether at least one background-work lease is active.
86///
87/// A platform backend reads this to decide whether the runtime keeps turning
88/// while the app is off screen. Both mobile backends drive composition from the
89/// frame path, and both stop that path when the surface is gone: Android drops
90/// its GPU resources on `TerminateWindow`, iOS stops receiving redraws. Anything
91/// posted to the UI dispatcher then waits until the user comes back, which is
92/// wrong for an app that told the OS it has work to finish.
93pub fn background_active() -> bool {
94    ACTIVE_LEASES.load(Ordering::Acquire) != 0
95}
96
97#[cfg(test)]
98mod tests {
99    use super::*;
100    use std::sync::atomic::{AtomicBool, Ordering};
101
102    #[test]
103    fn registration_round_trips() {
104        // The lease count is one number for the process, and the media service
105        // takes a lease of its own while it plays. Tests that read it take
106        // turns, or each sees the other's leases as its own.
107        let _services = crate::registry::test_service_guard();
108        clear_platform_background_activity();
109        struct Rec(AtomicBool);
110        impl BackgroundActivity for Rec {
111            fn set_active(&self, active: bool) {
112                self.0.store(active, Ordering::SeqCst);
113            }
114        }
115        let rec = Arc::new(Rec(AtomicBool::new(false)));
116        set_platform_background_activity(rec.clone());
117        let first = acquire_background_work();
118        assert!(rec.0.load(Ordering::SeqCst));
119        assert!(background_active());
120        let second = acquire_background_work();
121        drop(first);
122        assert!(background_active());
123        assert!(rec.0.load(Ordering::SeqCst));
124        drop(second);
125        assert!(!background_active());
126        assert!(!rec.0.load(Ordering::SeqCst));
127        clear_platform_background_activity();
128    }
129}
cranpose_services/background.rs

cranpose_services/
background.rs
