gio/auto/
cancellable.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::ffi;
6use glib::{prelude::*, translate::*};
7
8glib::wrapper! {
9    /// `GCancellable` allows operations to be cancelled.
10    ///
11    /// `GCancellable` is a thread-safe operation cancellation stack used
12    /// throughout GIO to allow for cancellation of synchronous and
13    /// asynchronous operations.
14    ///
15    /// ## Signals
16    ///
17    ///
18    /// #### `cancelled`
19    ///  Emitted when the operation has been cancelled.
20    ///
21    /// Can be used by implementations of cancellable operations. If the
22    /// operation is cancelled from another thread, the signal will be
23    /// emitted in the thread that cancelled the operation, not the
24    /// thread that is running the operation.
25    ///
26    /// Note that disconnecting from this signal (or any signal) in a
27    /// multi-threaded program is prone to race conditions. For instance
28    /// it is possible that a signal handler may be invoked even after
29    /// a call to g_signal_handler_disconnect() for that handler has
30    /// already returned.
31    ///
32    /// There is also a problem when cancellation happens right before
33    /// connecting to the signal. If this happens the signal will
34    /// unexpectedly not be emitted, and checking before connecting to
35    /// the signal leaves a race condition where this is still happening.
36    ///
37    /// In order to make it safe and easy to connect handlers there
38    /// are two helper functions: g_cancellable_connect() and
39    /// g_cancellable_disconnect() which protect against problems
40    /// like this.
41    ///
42    /// An example of how to us this:
43    ///
44    ///
45    /// **⚠️ The following code is in C ⚠️**
46    ///
47    /// ```C
48    ///     // Make sure we don't do unnecessary work if already cancelled
49    ///     if (g_cancellable_set_error_if_cancelled (cancellable, error))
50    ///       return;
51    ///
52    ///     // Set up all the data needed to be able to handle cancellation
53    ///     // of the operation
54    ///     my_data = my_data_new (...);
55    ///
56    ///     id = 0;
57    ///     if (cancellable)
58    ///       id = g_cancellable_connect (cancellable,
59    ///                       G_CALLBACK (cancelled_handler)
60    ///                       data, NULL);
61    ///
62    ///     // cancellable operation here...
63    ///
64    ///     g_cancellable_disconnect (cancellable, id);
65    ///
66    ///     // cancelled_handler is never called after this, it is now safe
67    ///     // to free the data
68    ///     my_data_free (my_data);
69    /// ```
70    ///
71    /// Note that the cancelled signal is emitted in the thread that
72    /// the user cancelled from, which may be the main thread. So, the
73    /// cancellable signal should not do something that can block.
74    ///
75    ///
76    ///
77    /// # Implements
78    ///
79    /// [`CancellableExt`][trait@crate::prelude::CancellableExt], [`trait@glib::ObjectExt`], [`CancellableExtManual`][trait@crate::prelude::CancellableExtManual]
80    #[doc(alias = "GCancellable")]
81    pub struct Cancellable(Object<ffi::GCancellable, ffi::GCancellableClass>);
82
83    match fn {
84        type_ => || ffi::g_cancellable_get_type(),
85    }
86}
87
88impl Cancellable {
89    pub const NONE: Option<&'static Cancellable> = None;
90
91    /// Creates a new #GCancellable object.
92    ///
93    /// Applications that want to start one or more operations
94    /// that should be cancellable should create a #GCancellable
95    /// and pass it to the operations.
96    ///
97    /// One #GCancellable can be used in multiple consecutive
98    /// operations or in multiple concurrent operations.
99    ///
100    /// # Returns
101    ///
102    /// a #GCancellable.
103    #[doc(alias = "g_cancellable_new")]
104    pub fn new() -> Cancellable {
105        unsafe { from_glib_full(ffi::g_cancellable_new()) }
106    }
107
108    /// Gets the top cancellable from the stack.
109    ///
110    /// # Returns
111    ///
112    /// a #GCancellable from the top
113    /// of the stack, or [`None`] if the stack is empty.
114    #[doc(alias = "g_cancellable_get_current")]
115    #[doc(alias = "get_current")]
116    pub fn current() -> Option<Cancellable> {
117        unsafe { from_glib_none(ffi::g_cancellable_get_current()) }
118    }
119}
120
121impl Default for Cancellable {
122    fn default() -> Self {
123        Self::new()
124    }
125}
126
127unsafe impl Send for Cancellable {}
128unsafe impl Sync for Cancellable {}
129
130mod sealed {
131    pub trait Sealed {}
132    impl<T: super::IsA<super::Cancellable>> Sealed for T {}
133}
134
135/// Trait containing all [`struct@Cancellable`] methods.
136///
137/// # Implementors
138///
139/// [`Cancellable`][struct@crate::Cancellable]
140pub trait CancellableExt: IsA<Cancellable> + sealed::Sealed + 'static {
141    /// Will set @self to cancelled, and will emit the
142    /// #GCancellable::cancelled signal. (However, see the warning about
143    /// race conditions in the documentation for that signal if you are
144    /// planning to connect to it.)
145    ///
146    /// This function is thread-safe. In other words, you can safely call
147    /// it from a thread other than the one running the operation that was
148    /// passed the @self.
149    ///
150    /// If @self is [`None`], this function returns immediately for convenience.
151    ///
152    /// The convention within GIO is that cancelling an asynchronous
153    /// operation causes it to complete asynchronously. That is, if you
154    /// cancel the operation from the same thread in which it is running,
155    /// then the operation's #GAsyncReadyCallback will not be invoked until
156    /// the application returns to the main loop.
157    #[doc(alias = "g_cancellable_cancel")]
158    fn cancel(&self) {
159        unsafe {
160            ffi::g_cancellable_cancel(self.as_ref().to_glib_none().0);
161        }
162    }
163
164    /// Gets the file descriptor for a cancellable job. This can be used to
165    /// implement cancellable operations on Unix systems. The returned fd will
166    /// turn readable when @self is cancelled.
167    ///
168    /// You are not supposed to read from the fd yourself, just check for
169    /// readable status. Reading to unset the readable status is done
170    /// with g_cancellable_reset().
171    ///
172    /// After a successful return from this function, you should use
173    /// g_cancellable_release_fd() to free up resources allocated for
174    /// the returned file descriptor.
175    ///
176    /// See also g_cancellable_make_pollfd().
177    ///
178    /// # Returns
179    ///
180    /// A valid file descriptor. `-1` if the file descriptor
181    /// is not supported, or on errors.
182    #[doc(alias = "g_cancellable_get_fd")]
183    #[doc(alias = "get_fd")]
184    fn fd(&self) -> i32 {
185        unsafe { ffi::g_cancellable_get_fd(self.as_ref().to_glib_none().0) }
186    }
187
188    /// Checks if a cancellable job has been cancelled.
189    ///
190    /// # Returns
191    ///
192    /// [`true`] if @self is cancelled,
193    /// FALSE if called with [`None`] or if item is not cancelled.
194    #[doc(alias = "g_cancellable_is_cancelled")]
195    fn is_cancelled(&self) -> bool {
196        unsafe {
197            from_glib(ffi::g_cancellable_is_cancelled(
198                self.as_ref().to_glib_none().0,
199            ))
200        }
201    }
202
203    //#[doc(alias = "g_cancellable_make_pollfd")]
204    //fn make_pollfd(&self, pollfd: /*Ignored*/&mut glib::PollFD) -> bool {
205    //    unsafe { TODO: call ffi:g_cancellable_make_pollfd() }
206    //}
207
208    /// Pops @self off the cancellable stack (verifying that @self
209    /// is on the top of the stack).
210    #[doc(alias = "g_cancellable_pop_current")]
211    fn pop_current(&self) {
212        unsafe {
213            ffi::g_cancellable_pop_current(self.as_ref().to_glib_none().0);
214        }
215    }
216
217    /// Pushes @self onto the cancellable stack. The current
218    /// cancellable can then be received using g_cancellable_get_current().
219    ///
220    /// This is useful when implementing cancellable operations in
221    /// code that does not allow you to pass down the cancellable object.
222    ///
223    /// This is typically called automatically by e.g. #GFile operations,
224    /// so you rarely have to call this yourself.
225    #[doc(alias = "g_cancellable_push_current")]
226    fn push_current(&self) {
227        unsafe {
228            ffi::g_cancellable_push_current(self.as_ref().to_glib_none().0);
229        }
230    }
231
232    /// Releases a resources previously allocated by g_cancellable_get_fd()
233    /// or g_cancellable_make_pollfd().
234    ///
235    /// For compatibility reasons with older releases, calling this function
236    /// is not strictly required, the resources will be automatically freed
237    /// when the @self is finalized. However, the @self will
238    /// block scarce file descriptors until it is finalized if this function
239    /// is not called. This can cause the application to run out of file
240    /// descriptors when many #GCancellables are used at the same time.
241    #[doc(alias = "g_cancellable_release_fd")]
242    fn release_fd(&self) {
243        unsafe {
244            ffi::g_cancellable_release_fd(self.as_ref().to_glib_none().0);
245        }
246    }
247}
248
249impl<O: IsA<Cancellable>> CancellableExt for O {}