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
use std::fmt::Formatter;
use std::ptr::null_mut;
use std::sync::atomic::{AtomicPtr, Ordering};
use std::sync::Arc;

/// Atomic reference holding a value, that's supposed to be shared - potentially between multiple
/// threads. Internally this value is hidden behind [Arc] reference, which is returned during
/// [AtomicRef::get] method. This cell doesn't allow to return &mut references to stored object.
/// Instead updates can be performed as lock-free operation mutating function
/// passed over during [AtomicRef::update] call.
///
/// Example:
/// ```rust
/// use yrs::atomic::AtomicRef;
///
/// let atom = AtomicRef::new(vec!["John"]);
/// atom.update(|users| {
///     let mut users_copy = users.cloned().unwrap_or_else(Vec::default);
///     users_copy.push("Susan");
///     users_copy
/// });
/// let users = atom.get(); // John, Susan
/// ```
/// **Important note**: since [AtomicRef::update] may call provided function multiple times (in
/// scenarios, when another thread intercepted update with its own update call), provided function
/// should be idempotent and preferably quick to execute.
#[repr(transparent)]
pub struct AtomicRef<T>(AtomicPtr<T>);

unsafe impl<T> Send for AtomicRef<T> {}
unsafe impl<T> Sync for AtomicRef<T> {}

impl<T> AtomicRef<T> {
    /// Creates a new instance of [AtomicRef]. This call boxes provided `value` and allocates it
    /// on a heap.
    pub fn new(value: T) -> Self {
        let arc = Arc::new(value);
        let ptr = Arc::into_raw(arc) as *mut _;
        AtomicRef(AtomicPtr::new(ptr))
    }

    /// Returns a reference to current state hold by the [AtomicRef]. Keep in mind that after
    /// acquiring it, it may not present the current view of the state, but instead be changed by
    /// the concurrent [AtomicRef::update] call.
    pub fn get(&self) -> Option<Arc<T>> {
        let ptr = self.0.load(Ordering::SeqCst);
        if ptr.is_null() {
            None
        } else {
            let arc = unsafe { Arc::from_raw(ptr) };
            let result = arc.clone();
            std::mem::forget(arc);
            Some(result)
        }
    }

    /// Updates stored value in place using provided function `f`, which takes read-only refrence
    /// to the most recently known state and producing new state in the result.
    ///
    /// **Important note**: since [AtomicRef::update] may call provided function multiple times (in
    /// scenarios, when another thread intercepted update with its own update call), provided
    /// function should be idempotent and preferably quick to execute.
    pub fn update<F>(&self, f: F)
    where
        F: Fn(Option<&T>) -> T,
    {
        loop {
            let old_ptr = self.0.load(Ordering::SeqCst);
            let old_value = unsafe { old_ptr.as_ref() };

            // modify copied value
            let new_value = f(old_value);

            let new_ptr = Arc::into_raw(Arc::new(new_value)) as *mut _;

            let swapped =
                self.0
                    .compare_exchange(old_ptr, new_ptr, Ordering::AcqRel, Ordering::Relaxed);

            match swapped {
                Ok(old) => {
                    if !old.is_null() {
                        unsafe { Arc::decrement_strong_count(old) }; // drop reference to old
                    }
                    break; // we succeeded
                }
                Err(new) => {
                    if !new.is_null() {
                        unsafe { Arc::decrement_strong_count(new) }; // drop reference to new and retry
                    }
                }
            }
        }
    }
}

impl<T> Drop for AtomicRef<T> {
    fn drop(&mut self) {
        unsafe {
            let ptr = self.0.load(Ordering::Acquire);
            if !ptr.is_null() {
                Arc::decrement_strong_count(ptr);
            }
        }
    }
}

impl<T: std::fmt::Debug> std::fmt::Debug for AtomicRef<T> {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        let value = self.get();
        write!(f, "AtomicRef({:?})", value.as_deref())
    }
}

impl<T> Default for AtomicRef<T> {
    fn default() -> Self {
        AtomicRef(AtomicPtr::new(null_mut()))
    }
}

#[cfg(test)]
mod test {
    use crate::atomic::AtomicRef;

    #[test]
    fn init_get() {
        let atom = AtomicRef::new(1);
        let value = atom.get();
        assert_eq!(value.as_deref().cloned(), Some(1));
    }

    #[test]
    fn update() {
        let atom = AtomicRef::new(vec!["John"]);
        let old_users = atom.get().unwrap();
        let actual: &[&str] = &old_users;
        assert_eq!(actual, &["John"]);

        atom.update(|users| {
            let mut users_copy = users.cloned().unwrap_or_else(Vec::default);
            users_copy.push("Susan");
            users_copy
        });

        // after update new Arc ptr data returns updated content
        let new_users = atom.get().unwrap();
        let actual: &[&str] = &new_users;
        assert_eq!(actual, &["John", "Susan"]);

        // old Arc ptr data is unchanged
        let actual: &[&str] = &old_users;
        assert_eq!(actual, &["John"]);
    }
}