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 {}