gio/
cancellable.rs

1// Take a look at the license at the top of the repository in the LICENSE file.
2
3use std::{future::IntoFuture, num::NonZeroU64};
4
5use futures_channel::oneshot;
6use futures_core::Future;
7use glib::{prelude::*, translate::*};
8
9use crate::{ffi, Cancellable};
10
11// rustdoc-stripper-ignore-next
12/// The id of a cancelled handler that is returned by `CancellableExtManual::connect`. This type is
13/// analogous to [`glib::SignalHandlerId`].
14#[derive(Debug, Eq, PartialEq)]
15#[repr(transparent)]
16pub struct CancelledHandlerId(NonZeroU64);
17
18impl CancelledHandlerId {
19    // rustdoc-stripper-ignore-next
20    /// Returns the internal signal handler ID.
21    #[allow(clippy::missing_safety_doc)]
22    pub unsafe fn as_raw(&self) -> libc::c_ulong {
23        self.0.get() as libc::c_ulong
24    }
25}
26
27impl TryFromGlib<libc::c_ulong> for CancelledHandlerId {
28    type Error = GlibNoneError;
29    #[inline]
30    unsafe fn try_from_glib(val: libc::c_ulong) -> Result<Self, GlibNoneError> {
31        NonZeroU64::new(val as _).map(Self).ok_or(GlibNoneError)
32    }
33}
34
35pub trait CancellableExtManual: IsA<Cancellable> {
36    // rustdoc-stripper-ignore-next
37    /// Convenience function to connect to the `signal::Cancellable::cancelled` signal. Also
38    /// handles the race condition that may happen if the cancellable is cancelled right before
39    /// connecting. If the operation is cancelled from another thread, `callback` will be called
40    /// in the thread that cancelled the operation, not the thread that is running the operation.
41    /// This may be the main thread, so the callback should not do something that can block.
42    ///
43    /// `callback` is called at most once, either directly at the time of the connect if `self` is
44    /// already cancelled, or when `self` is cancelled in some thread.
45    ///
46    /// Since GLib 2.40, the lock protecting `self` is not held when `callback` is invoked. This
47    /// lifts a restriction in place for earlier GLib versions which now makes it easier to write
48    /// cleanup code that unconditionally invokes e.g.
49    /// [`CancellableExt::cancel()`][crate::prelude::CancellableExt::cancel()].
50    ///
51    /// # Returns
52    ///
53    /// The id of the signal handler or `None` if `self` has already been cancelled.
54    #[doc(alias = "g_cancellable_connect")]
55    fn connect_cancelled<F: FnOnce(&Self) + Send + 'static>(
56        &self,
57        callback: F,
58    ) -> Option<CancelledHandlerId> {
59        unsafe extern "C" fn connect_trampoline<P: IsA<Cancellable>, F: FnOnce(&P)>(
60            this: *mut ffi::GCancellable,
61            callback: glib::ffi::gpointer,
62        ) {
63            let callback: &mut Option<F> = &mut *(callback as *mut Option<F>);
64            let callback = callback
65                .take()
66                .expect("Cancellable::cancel() closure called multiple times");
67            callback(Cancellable::from_glib_borrow(this).unsafe_cast_ref())
68        }
69
70        unsafe extern "C" fn destroy_closure<F>(ptr: glib::ffi::gpointer) {
71            let _ = Box::<Option<F>>::from_raw(ptr as *mut _);
72        }
73
74        let callback: Box<Option<F>> = Box::new(Some(callback));
75        unsafe {
76            from_glib(ffi::g_cancellable_connect(
77                self.as_ptr() as *mut _,
78                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
79                    connect_trampoline::<Self, F> as *const (),
80                )),
81                Box::into_raw(callback) as *mut _,
82                Some(destroy_closure::<F>),
83            ))
84        }
85    }
86    // rustdoc-stripper-ignore-next
87    /// Local variant of [`Self::connect_cancelled`].
88    #[doc(alias = "g_cancellable_connect")]
89    fn connect_cancelled_local<F: FnOnce(&Self) + 'static>(
90        &self,
91        callback: F,
92    ) -> Option<CancelledHandlerId> {
93        let callback = glib::thread_guard::ThreadGuard::new(callback);
94
95        self.connect_cancelled(move |obj| (callback.into_inner())(obj))
96    }
97    // rustdoc-stripper-ignore-next
98    /// Disconnects a handler from a cancellable instance. Additionally, in the event that a signal
99    /// handler is currently running, this call will block until the handler has finished. Calling
100    /// this function from a callback registered with [`Self::connect_cancelled`] will therefore
101    /// result in a deadlock.
102    ///
103    /// This avoids a race condition where a thread cancels at the same time as the cancellable
104    /// operation is finished and the signal handler is removed.
105    #[doc(alias = "g_cancellable_disconnect")]
106    fn disconnect_cancelled(&self, id: CancelledHandlerId) {
107        unsafe { ffi::g_cancellable_disconnect(self.as_ptr() as *mut _, id.as_raw()) };
108    }
109    // rustdoc-stripper-ignore-next
110    /// Returns a `Future` that completes when the cancellable becomes cancelled. Completes
111    /// immediately if the cancellable is already cancelled.
112    fn future(&self) -> std::pin::Pin<Box<dyn Future<Output = ()> + Send + Sync + 'static>> {
113        let cancellable = self.as_ref().clone();
114        let (tx, rx) = oneshot::channel();
115        let id = cancellable.connect_cancelled(move |_| {
116            let _ = tx.send(());
117        });
118        Box::pin(async move {
119            rx.await.unwrap();
120            if let Some(id) = id {
121                cancellable.disconnect_cancelled(id);
122            }
123        })
124    }
125    // rustdoc-stripper-ignore-next
126    /// Set an error if the cancellable is already cancelled.
127    #[doc(alias = "g_cancellable_set_error_if_cancelled")]
128    fn set_error_if_cancelled(&self) -> Result<(), glib::Error> {
129        unsafe {
130            let mut error = std::ptr::null_mut();
131            let is_ok = ffi::g_cancellable_set_error_if_cancelled(
132                self.as_ref().to_glib_none().0,
133                &mut error,
134            );
135            // Here's the special case, this function has an inverted
136            // return value for the error case.
137            debug_assert_eq!(is_ok == glib::ffi::GFALSE, error.is_null());
138            if error.is_null() {
139                Ok(())
140            } else {
141                Err(from_glib_full(error))
142            }
143        }
144    }
145}
146
147impl<O: IsA<Cancellable>> CancellableExtManual for O {}
148
149impl IntoFuture for Cancellable {
150    type Output = ();
151
152    type IntoFuture = std::pin::Pin<Box<dyn Future<Output = ()> + Send + Sync + 'static>>;
153
154    fn into_future(self) -> Self::IntoFuture {
155        self.future()
156    }
157}
158
159impl IntoFuture for &Cancellable {
160    type Output = ();
161
162    type IntoFuture = std::pin::Pin<Box<dyn Future<Output = ()> + Send + Sync + 'static>>;
163
164    fn into_future(self) -> Self::IntoFuture {
165        self.future()
166    }
167}
168
169#[cfg(test)]
170mod tests {
171    use super::*;
172
173    use crate::prelude::*;
174
175    #[test]
176    fn cancellable_callback() {
177        let c = Cancellable::new();
178        let id = c.connect_cancelled(|_| {});
179        c.cancel(); // if it doesn't crash at this point, then we're good to go!
180        c.disconnect_cancelled(id.unwrap());
181    }
182
183    #[test]
184    fn cancellable_callback_local() {
185        let c = Cancellable::new();
186        let id = c.connect_cancelled_local(|_| {});
187        c.cancel(); // if it doesn't crash at this point, then we're good to go!
188        c.disconnect_cancelled(id.unwrap());
189    }
190
191    #[test]
192    fn cancellable_error_if_cancelled() {
193        let c = Cancellable::new();
194        c.cancel();
195        assert!(c.set_error_if_cancelled().is_err());
196    }
197
198    #[test]
199    fn cancellable_future() {
200        let c = Cancellable::new();
201        c.cancel();
202        glib::MainContext::new().block_on(c.future());
203    }
204
205    #[test]
206    fn cancellable_future_thread() {
207        let cancellable = Cancellable::new();
208        let c = cancellable.clone();
209        std::thread::spawn(move || c.cancel()).join().unwrap();
210        glib::MainContext::new().block_on(cancellable.future());
211    }
212
213    #[test]
214    fn cancellable_future_delayed() {
215        let ctx = glib::MainContext::new();
216        let c = Cancellable::new();
217        let (tx, rx) = oneshot::channel();
218        {
219            let c = c.clone();
220            ctx.spawn_local(async move {
221                c.future().await;
222                tx.send(()).unwrap();
223            });
224        }
225        std::thread::spawn(move || c.cancel()).join().unwrap();
226        ctx.block_on(rx).unwrap();
227    }
228}
gio/cancellable.rs

gio/
cancellable.rs
