vfs/
temp_clone.rs

1// Copyright 2023 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5use fidl::HandleBased;
6use fuchsia_sync::{Condvar, Mutex};
7use std::cell::UnsafeCell;
8use std::collections::hash_map::Entry;
9use std::collections::{HashMap, VecDeque};
10use std::marker::PhantomData;
11use std::mem::ManuallyDrop;
12use std::ops::Deref;
13use std::sync::{Arc, OnceLock, Weak};
14
15#[cfg(not(target_os = "fuchsia"))]
16use fuchsia_async::emulated_handle::zx_handle_t;
17#[cfg(target_os = "fuchsia")]
18use zx::sys::zx_handle_t;
19
20/// A wrapper around zircon handles that allows them to be temporarily cloned. These temporary
21/// clones can be used with `unblock` below which requires callbacks with static lifetime.  This is
22/// similar to Arc<T>, except that whilst there are no clones, there is no memory overhead, and
23/// there's no performance overhead to use them just as you would without the wrapper, except for a
24/// small overhead when they are dropped. The wrapper ensures that the handle is only dropped when
25/// there are no references.
26pub struct TempClonable<T: HandleBased>(ManuallyDrop<T>);
27
28impl<T: HandleBased> TempClonable<T> {
29    /// Returns a new handle that can be temporarily cloned.
30    pub fn new(handle: T) -> Self {
31        Self(ManuallyDrop::new(handle))
32    }
33}
34
35impl<T: HandleBased> Deref for TempClonable<T> {
36    type Target = T;
37
38    fn deref(&self) -> &T {
39        &self.0
40    }
41}
42
43impl<T: HandleBased> TempClonable<T> {
44    /// Creates a temporary clone of the handle. The clone should only exist temporarily.
45    ///
46    /// # Panics
47    ///
48    /// Panics if the handle is invalid.
49    pub fn temp_clone(&self) -> TempClone<T> {
50        assert!(!self.is_invalid_handle());
51        let mut clones = clones().lock();
52        let raw_handle = self.0.raw_handle();
53        TempClone {
54            handle: match clones.entry(raw_handle) {
55                Entry::Occupied(mut o) => {
56                    if let Some(clone) = o.get().upgrade() {
57                        clone
58                    } else {
59                        // The last strong reference was dropped but the entry hasn't been removed
60                        // yet. This must be racing with `TempHandle::drop`. Replace the
61                        // `TempHandle`.
62                        let clone =
63                            Arc::new(TempHandle { raw_handle, tombstone: UnsafeCell::new(false) });
64                        *o.get_mut() = Arc::downgrade(&clone);
65                        clone
66                    }
67                }
68                Entry::Vacant(v) => {
69                    let clone =
70                        Arc::new(TempHandle { raw_handle, tombstone: UnsafeCell::new(false) });
71                    v.insert(Arc::downgrade(&clone));
72                    clone
73                }
74            },
75            marker: PhantomData,
76        }
77    }
78}
79
80impl<T: HandleBased> Drop for TempClonable<T> {
81    fn drop(&mut self) {
82        if let Some(handle) = clones().lock().remove(&self.0.raw_handle()).and_then(|c| c.upgrade())
83        {
84            // There are still some temporary clones alive, so mark the handle with a tombstone.
85
86            // SAFETY: This is the only unsafe place where we access `tombstone`. We're are holding
87            // the clones lock which ensures no other thread is concurrently accessing it, but it
88            // wouldn't normally happen anyway because it would mean there were multiple
89            // TempClonable instances wrapping the same handle, which shouldn't happen.
90            unsafe { *handle.tombstone.get() = true };
91            return;
92        }
93
94        // SAFETY: There are no temporary clones, so we can drop the handle now. No more clones can
95        // be made and it should be clear we meet the safety requirements of ManuallyDrop.
96        unsafe { ManuallyDrop::drop(&mut self.0) }
97    }
98}
99
100type Clones = Mutex<HashMap<zx_handle_t, Weak<TempHandle>>>;
101
102/// Returns the global instance which keeps track of temporary clones.
103fn clones() -> &'static Clones {
104    static CLONES: OnceLock<Clones> = OnceLock::new();
105    CLONES.get_or_init(|| Mutex::new(HashMap::new()))
106}
107
108pub struct TempClone<T> {
109    handle: Arc<TempHandle>,
110    marker: PhantomData<T>,
111}
112
113impl<T> Deref for TempClone<T> {
114    type Target = T;
115
116    fn deref(&self) -> &T {
117        // SAFETY: T is repr(transparent) and stores zx_handle_t.
118        unsafe { std::mem::transmute::<&zx_handle_t, &T>(&self.handle.raw_handle) }
119    }
120}
121
122struct TempHandle {
123    raw_handle: zx_handle_t,
124    tombstone: UnsafeCell<bool>,
125}
126
127unsafe impl Send for TempHandle {}
128unsafe impl Sync for TempHandle {}
129
130impl Drop for TempHandle {
131    fn drop(&mut self) {
132        if *self.tombstone.get_mut() {
133            // SAFETY: The primary handle has been dropped and it is our job to clean up the
134            // handle. There are no memory safety issues here.
135            unsafe { fidl::Handle::from_raw(self.raw_handle) };
136        } else {
137            if let Entry::Occupied(o) = clones().lock().entry(self.raw_handle) {
138                // There's a small window where another TempHandle could have been inserted, so
139                // before removing this entry, check for a match.
140                if std::ptr::eq(o.get().as_ptr(), self) {
141                    o.remove_entry();
142                }
143            }
144        }
145    }
146}
147
148/// This is similar to fuchsia-async's unblock except that it used a fixed size thread pool which
149/// has the advantage of not making traces difficult to decipher because of many threads being
150/// spawned.
151pub async fn unblock<T: 'static + Send>(f: impl FnOnce() -> T + Send + 'static) -> T {
152    const NUM_THREADS: u8 = 2;
153
154    struct State {
155        queue: Mutex<VecDeque<Box<dyn FnOnce() + Send + 'static>>>,
156        cvar: Condvar,
157    }
158
159    static STATE: OnceLock<State> = OnceLock::new();
160
161    let mut start_threads = false;
162    let state = STATE.get_or_init(|| {
163        start_threads = true;
164        State { queue: Mutex::new(VecDeque::new()), cvar: Condvar::new() }
165    });
166
167    if start_threads {
168        for _ in 0..NUM_THREADS {
169            std::thread::spawn(|| {
170                loop {
171                    let item = {
172                        let mut queue = state.queue.lock();
173                        loop {
174                            if let Some(item) = queue.pop_front() {
175                                break item;
176                            }
177                            state.cvar.wait(&mut queue);
178                        }
179                    };
180                    item();
181                }
182            });
183        }
184    }
185
186    let (tx, rx) = futures::channel::oneshot::channel();
187    state.queue.lock().push_back(Box::new(move || {
188        let _ = tx.send(f());
189    }));
190    state.cvar.notify_one();
191
192    rx.await.unwrap()
193}
194
195#[cfg(target_os = "fuchsia")]
196#[cfg(test)]
197mod tests {
198    use super::{TempClonable, clones};
199
200    use std::sync::Arc;
201
202    #[test]
203    fn test_temp_clone() {
204        let parent_vmo = zx::Vmo::create(100).expect("create failed");
205
206        {
207            let temp_clone = {
208                let vmo = TempClonable::new(
209                    parent_vmo
210                        .create_child(zx::VmoChildOptions::REFERENCE, 0, 0)
211                        .expect("create_child failed"),
212                );
213
214                vmo.write(b"foo", 0).expect("write failed");
215                {
216                    // Create and read from a temporary clone.
217                    let temp_clone2 = vmo.temp_clone();
218                    assert_eq!(&temp_clone2.read_to_vec(0, 3).expect("read_to_vec failed"), b"foo");
219                }
220
221                // We should still be able to read from the primary handle.
222                assert_eq!(&vmo.read_to_vec(0, 3).expect("read_to_vec failed"), b"foo");
223
224                // Create another vmo which should get cleaned up when the primary handle is
225                // dropped.
226                let vmo2 = TempClonable::new(
227                    parent_vmo
228                        .create_child(zx::VmoChildOptions::REFERENCE, 0, 0)
229                        .expect("create_child failed"),
230                );
231                // Create and immediately drop a temporary clone.
232                vmo2.temp_clone();
233
234                // Take another clone that will get dropped after we take the clone below.
235                let _clone1 = vmo.temp_clone();
236
237                // And return another clone.
238                vmo.temp_clone()
239            };
240
241            // The primary handle has been dropped, but we should still be able to
242            // read via temp_clone.
243            assert_eq!(&temp_clone.read_to_vec(0, 3).expect("read_to_vec failed"), b"foo");
244        }
245
246        // Make sure that all the VMOs got properly cleaned up.
247        assert_eq!(parent_vmo.info().expect("info failed").num_children, 0);
248        assert!(clones().lock().is_empty());
249    }
250
251    #[test]
252    fn test_race() {
253        let parent_vmo = zx::Vmo::create(100).expect("create failed");
254
255        {
256            let vmo = Arc::new(TempClonable::new(
257                parent_vmo
258                    .create_child(zx::VmoChildOptions::REFERENCE, 0, 0)
259                    .expect("create_child failed"),
260            ));
261            vmo.write(b"foo", 0).expect("write failed");
262
263            let vmo_clone = vmo.clone();
264
265            let t1 = std::thread::spawn(move || {
266                for _ in 0..1000 {
267                    assert_eq!(
268                        &vmo.temp_clone().read_to_vec(0, 3).expect("read_to_vec failed"),
269                        b"foo"
270                    );
271                }
272            });
273
274            let t2 = std::thread::spawn(move || {
275                for _ in 0..1000 {
276                    assert_eq!(
277                        &vmo_clone.temp_clone().read_to_vec(0, 3).expect("read_to_vec failed"),
278                        b"foo"
279                    );
280                }
281            });
282
283            let _ = t1.join();
284            let _ = t2.join();
285        }
286
287        // Make sure that all the VMOs got properly cleaned up.
288        assert_eq!(parent_vmo.info().expect("info failed").num_children, 0);
289        assert!(clones().lock().is_empty());
290    }
291}
vfs/temp_clone.rs

vfs/
temp_clone.rs
