Skip to main content

sui_reactive/
lib.rs

1#![forbid(unsafe_code)]
2
3//! Architecture-neutral observable values for SUI.
4//!
5//! This crate owns state and change notification only. It does not depend on
6//! the SUI widget runtime, so applications may adapt other stores through
7//! [`Observable`] without adopting a SUI-owned application architecture.
8
9use std::{
10    fmt,
11    marker::PhantomData,
12    sync::{
13        Arc, Mutex, RwLock, Weak,
14        atomic::{AtomicU64, Ordering},
15    },
16};
17
18static NEXT_SOURCE_ID: AtomicU64 = AtomicU64::new(1);
19
20/// Stable identity for one observable source.
21#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
22pub struct SourceId(u64);
23
24impl SourceId {
25    pub const fn get(self) -> u64 {
26        self.0
27    }
28
29    /// Allocate a process-unique observable source identifier.
30    pub fn new() -> Self {
31        Self(NEXT_SOURCE_ID.fetch_add(1, Ordering::Relaxed))
32    }
33}
34
35impl Default for SourceId {
36    fn default() -> Self {
37        Self::new()
38    }
39}
40
41/// Metadata emitted when an observable value changes.
42#[derive(Debug, Clone, PartialEq, Eq)]
43pub struct Change {
44    pub source_id: SourceId,
45    pub source_name: Arc<str>,
46    pub version: u64,
47}
48
49type ObserverCallback = dyn Fn(Change) + Send + Sync + 'static;
50
51struct ObserverInner {
52    callback: Box<ObserverCallback>,
53}
54
55/// Cloneable change observer used by observable implementations.
56#[derive(Clone)]
57pub struct Observer {
58    inner: Arc<ObserverInner>,
59}
60
61impl Observer {
62    pub fn new(callback: impl Fn(Change) + Send + Sync + 'static) -> Self {
63        Self {
64            inner: Arc::new(ObserverInner {
65                callback: Box::new(callback),
66            }),
67        }
68    }
69
70    pub fn notify(&self, change: Change) {
71        (self.inner.callback)(change);
72    }
73
74    pub fn downgrade(&self) -> WeakObserver {
75        WeakObserver {
76            inner: Arc::downgrade(&self.inner),
77        }
78    }
79}
80
81impl fmt::Debug for Observer {
82    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
83        formatter.debug_struct("Observer").finish_non_exhaustive()
84    }
85}
86
87/// Weak observer reference suitable for storage inside custom observables.
88#[derive(Clone)]
89pub struct WeakObserver {
90    inner: Weak<ObserverInner>,
91}
92
93impl WeakObserver {
94    /// Notify the observer, returning `false` after its subscription was
95    /// dropped.
96    pub fn notify(&self, change: Change) -> bool {
97        let Some(observer) = self.inner.upgrade() else {
98            return false;
99        };
100        (observer.callback)(change);
101        true
102    }
103}
104
105impl fmt::Debug for WeakObserver {
106    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
107        formatter
108            .debug_struct("WeakObserver")
109            .finish_non_exhaustive()
110    }
111}
112
113/// Keeps an observable subscription alive.
114///
115/// Dropping the guard releases the strong observer reference. Sources retain
116/// only weak references and prune them during later notifications.
117pub struct Subscription {
118    _observer: Observer,
119}
120
121impl Subscription {
122    pub fn new(observer: Observer) -> Self {
123        Self {
124            _observer: observer,
125        }
126    }
127}
128
129impl fmt::Debug for Subscription {
130    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
131        formatter
132            .debug_struct("Subscription")
133            .finish_non_exhaustive()
134    }
135}
136
137/// Readable value that can notify subscribers after meaningful changes.
138///
139/// SUI's runtime consumes this trait, so applications may provide adapters for
140/// reducer stores, channels, actor snapshots, or other state architectures.
141pub trait Observable<T> {
142    fn source_id(&self) -> SourceId;
143    fn source_name(&self) -> Arc<str>;
144    fn get(&self) -> T;
145    fn subscribe(&self, observer: Observer) -> Subscription;
146}
147
148struct SignalInner<T> {
149    id: SourceId,
150    name: Arc<str>,
151    value: RwLock<T>,
152    version: AtomicU64,
153    observers: Mutex<Vec<Weak<ObserverInner>>>,
154}
155
156/// Cloneable observable storage with equality-deduplicated writes.
157pub struct Signal<T> {
158    inner: Arc<SignalInner<T>>,
159}
160
161impl<T> Clone for Signal<T> {
162    fn clone(&self) -> Self {
163        Self {
164            inner: Arc::clone(&self.inner),
165        }
166    }
167}
168
169impl<T> fmt::Debug for Signal<T>
170where
171    T: fmt::Debug + Clone,
172{
173    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
174        formatter
175            .debug_struct("Signal")
176            .field("id", &self.inner.id)
177            .field("name", &self.inner.name)
178            .field("value", &self.read_value())
179            .field("version", &self.version())
180            .finish()
181    }
182}
183
184impl<T> Signal<T> {
185    pub fn new(value: T) -> Self {
186        Self::named("Signal", value)
187    }
188
189    pub fn named(name: impl Into<Arc<str>>, value: T) -> Self {
190        Self {
191            inner: Arc::new(SignalInner {
192                id: SourceId::new(),
193                name: name.into(),
194                value: RwLock::new(value),
195                version: AtomicU64::new(0),
196                observers: Mutex::new(Vec::new()),
197            }),
198        }
199    }
200
201    pub fn source_id(&self) -> SourceId {
202        self.inner.id
203    }
204
205    pub fn source_name(&self) -> Arc<str> {
206        Arc::clone(&self.inner.name)
207    }
208
209    pub fn version(&self) -> u64 {
210        self.inner.version.load(Ordering::Acquire)
211    }
212
213    pub fn get(&self) -> T
214    where
215        T: Clone,
216    {
217        self.read_value()
218    }
219
220    pub fn set(&self, value: T) -> bool
221    where
222        T: PartialEq,
223    {
224        {
225            let mut current = self
226                .inner
227                .value
228                .write()
229                .unwrap_or_else(std::sync::PoisonError::into_inner);
230            if *current == value {
231                return false;
232            }
233            *current = value;
234        }
235        self.notify();
236        true
237    }
238
239    pub fn update(&self, update: impl FnOnce(&mut T)) -> bool
240    where
241        T: Clone + PartialEq,
242    {
243        {
244            let mut current = self
245                .inner
246                .value
247                .write()
248                .unwrap_or_else(std::sync::PoisonError::into_inner);
249            let previous = current.clone();
250            update(&mut current);
251            if *current == previous {
252                return false;
253            }
254        }
255        self.notify();
256        true
257    }
258
259    pub fn select<U>(
260        &self,
261        select: impl Fn(&T) -> U + Send + Sync + 'static,
262    ) -> Selector<Self, T, U>
263    where
264        T: Clone + Send + Sync + 'static,
265        U: Clone + PartialEq + Send + Sync + 'static,
266    {
267        self.select_named("Selector", select)
268    }
269
270    pub fn select_named<U>(
271        &self,
272        name: impl Into<Arc<str>>,
273        select: impl Fn(&T) -> U + Send + Sync + 'static,
274    ) -> Selector<Self, T, U>
275    where
276        T: Clone + Send + Sync + 'static,
277        U: Clone + PartialEq + Send + Sync + 'static,
278    {
279        Selector::new(name, self.clone(), select)
280    }
281
282    fn read_value(&self) -> T
283    where
284        T: Clone,
285    {
286        self.inner
287            .value
288            .read()
289            .unwrap_or_else(std::sync::PoisonError::into_inner)
290            .clone()
291    }
292
293    fn notify(&self) {
294        let version = self.inner.version.fetch_add(1, Ordering::AcqRel) + 1;
295        let change = Change {
296            source_id: self.inner.id,
297            source_name: Arc::clone(&self.inner.name),
298            version,
299        };
300        let observers = {
301            let mut observers = self
302                .inner
303                .observers
304                .lock()
305                .unwrap_or_else(std::sync::PoisonError::into_inner);
306            let mut live = Vec::with_capacity(observers.len());
307            observers.retain(|observer| {
308                if let Some(observer) = observer.upgrade() {
309                    live.push(observer);
310                    true
311                } else {
312                    false
313                }
314            });
315            live
316        };
317        for observer in observers {
318            (observer.callback)(change.clone());
319        }
320    }
321}
322
323impl<T> Observable<T> for Signal<T>
324where
325    T: Clone + 'static,
326{
327    fn source_id(&self) -> SourceId {
328        self.source_id()
329    }
330
331    fn source_name(&self) -> Arc<str> {
332        self.source_name()
333    }
334
335    fn get(&self) -> T {
336        self.get()
337    }
338
339    fn subscribe(&self, observer: Observer) -> Subscription {
340        self.inner
341            .observers
342            .lock()
343            .unwrap_or_else(std::sync::PoisonError::into_inner)
344            .push(Arc::downgrade(&observer.inner));
345        Subscription::new(observer)
346    }
347}
348
349struct SelectorInner<S, I, O> {
350    id: SourceId,
351    name: Arc<str>,
352    source: S,
353    select: Arc<dyn Fn(&I) -> O + Send + Sync>,
354    version: AtomicU64,
355    _input: PhantomData<fn(I)>,
356}
357
358/// Equality-deduplicated derived observable.
359pub struct Selector<S, I, O> {
360    inner: Arc<SelectorInner<S, I, O>>,
361}
362
363impl<S, I, O> Clone for Selector<S, I, O> {
364    fn clone(&self) -> Self {
365        Self {
366            inner: Arc::clone(&self.inner),
367        }
368    }
369}
370
371impl<S, I, O> Selector<S, I, O> {
372    pub fn new(
373        name: impl Into<Arc<str>>,
374        source: S,
375        select: impl Fn(&I) -> O + Send + Sync + 'static,
376    ) -> Self {
377        Self {
378            inner: Arc::new(SelectorInner {
379                id: SourceId::new(),
380                name: name.into(),
381                source,
382                select: Arc::new(select),
383                version: AtomicU64::new(0),
384                _input: PhantomData,
385            }),
386        }
387    }
388}
389
390impl<S, I, O> Observable<O> for Selector<S, I, O>
391where
392    S: Observable<I> + Clone + Send + Sync + 'static,
393    I: Clone + Send + Sync + 'static,
394    O: Clone + PartialEq + Send + Sync + 'static,
395{
396    fn source_id(&self) -> SourceId {
397        self.inner.id
398    }
399
400    fn source_name(&self) -> Arc<str> {
401        Arc::clone(&self.inner.name)
402    }
403
404    fn get(&self) -> O {
405        (self.inner.select)(&self.inner.source.get())
406    }
407
408    fn subscribe(&self, observer: Observer) -> Subscription {
409        let last = Arc::new(Mutex::new(self.get()));
410        let source = self.inner.source.clone();
411        let select = Arc::clone(&self.inner.select);
412        let selector = Arc::clone(&self.inner);
413        let source_observer = Observer::new(move |_change| {
414            let next = select(&source.get());
415            let version = {
416                let mut previous = last
417                    .lock()
418                    .unwrap_or_else(std::sync::PoisonError::into_inner);
419                if *previous == next {
420                    return;
421                }
422                *previous = next;
423                selector.version.fetch_add(1, Ordering::AcqRel) + 1
424            };
425            // Observers may synchronously write back to the source and reenter
426            // this subscription. Never call application code with `last` locked.
427            observer.notify(Change {
428                source_id: selector.id,
429                source_name: Arc::clone(&selector.name),
430                version,
431            });
432        });
433        self.inner.source.subscribe(source_observer)
434    }
435}
436
437#[cfg(test)]
438mod tests {
439    use super::*;
440    use std::sync::atomic::AtomicUsize;
441
442    #[test]
443    fn signal_notifies_only_for_meaningful_changes() {
444        let signal = Signal::named("count", 1usize);
445        let notifications = Arc::new(AtomicUsize::new(0));
446        let count = Arc::clone(&notifications);
447        let _subscription = signal.subscribe(Observer::new(move |_| {
448            count.fetch_add(1, Ordering::Relaxed);
449        }));
450
451        assert!(!signal.set(1));
452        assert!(signal.set(2));
453        assert_eq!(notifications.load(Ordering::Relaxed), 1);
454        assert_eq!(signal.version(), 1);
455    }
456
457    #[test]
458    fn selector_deduplicates_unrelated_source_changes() {
459        #[derive(Clone, PartialEq)]
460        struct State {
461            selected: usize,
462            detail: String,
463        }
464
465        let state = Signal::new(State {
466            selected: 0,
467            detail: "first".to_string(),
468        });
469        let selected = state.select_named("selected", |state| state.selected);
470        let notifications = Arc::new(AtomicUsize::new(0));
471        let count = Arc::clone(&notifications);
472        let _subscription = selected.subscribe(Observer::new(move |_| {
473            count.fetch_add(1, Ordering::Relaxed);
474        }));
475
476        state.update(|state| state.detail = "second".to_string());
477        assert_eq!(notifications.load(Ordering::Relaxed), 0);
478        state.update(|state| state.selected = 1);
479        assert_eq!(notifications.load(Ordering::Relaxed), 1);
480        assert_eq!(selected.get(), 1);
481    }
482
483    #[test]
484    fn selector_observer_can_write_back_to_its_source() {
485        let (done, completed) = std::sync::mpsc::channel();
486        let worker = std::thread::spawn(move || {
487            let source = Signal::new(0_u32);
488            let selected = source.select(|value| *value);
489            let writer = source.clone();
490            let observed = Arc::new(Mutex::new(Vec::new()));
491            let values = Arc::clone(&observed);
492            let _subscription = selected.subscribe(Observer::new(move |_| {
493                let value = writer.get();
494                values.lock().unwrap().push(value);
495                if value == 1 {
496                    writer.set(2);
497                }
498            }));
499            source.set(1);
500            // An equal write must still be deduplicated after reentrant delivery.
501            assert!(!source.set(2));
502            done.send((source.get(), observed.lock().unwrap().clone()))
503                .unwrap();
504        });
505        let (value, observed) = completed
506            .recv_timeout(std::time::Duration::from_secs(5))
507            .expect("selector source write-back deadlocked");
508        worker.join().unwrap();
509        assert_eq!(value, 2);
510        assert_eq!(observed, vec![1, 2]);
511    }
512}