glib/auto/
source.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, translate::*};
6
7crate::wrapper! {
8    /// The `GSource` struct is an opaque data type
9    /// representing an event source.
10    // rustdoc-stripper-ignore-next-stop
11    /// The `GSource` struct is an opaque data type
12    /// representing an event source.
13    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
14    pub struct Source(Shared<ffi::GSource>);
15
16    match fn {
17        ref => |ptr| ffi::g_source_ref(ptr),
18        unref => |ptr| ffi::g_source_unref(ptr),
19        type_ => || ffi::g_source_get_type(),
20    }
21}
22
23impl Source {
24    //#[doc(alias = "g_source_new")]
25    //pub fn new(source_funcs: /*Ignored*/&mut SourceFuncs, struct_size: u32) -> Source {
26    //    unsafe { TODO: call ffi:g_source_new() }
27    //}
28
29    /// Adds @child_source to @self as a ‘polled’ source.
30    ///
31    /// When @self is added to a [`MainContext`][crate::MainContext], @child_source will be
32    /// automatically added with the same priority. When @child_source is triggered,
33    /// it will cause @self to dispatch (in addition to calling its own callback),
34    /// and when @self is destroyed, it will destroy @child_source as well.
35    ///
36    /// The @self will also still be dispatched if its own prepare/check functions
37    /// indicate that it is ready.
38    ///
39    /// If you don’t need @child_source to do anything on its own when it
40    /// triggers, you can call `g_source_set_dummy_callback()` on it to set a
41    /// callback that does nothing (except return true if appropriate).
42    ///
43    /// The @self will hold a reference on @child_source while @child_source
44    /// is attached to it.
45    ///
46    /// This API is only intended to be used by implementations of [`Source`][crate::Source].
47    /// Do not call this API on a [`Source`][crate::Source] that you did not create.
48    /// ## `child_source`
49    /// a second source that @self should ‘poll’
50    // rustdoc-stripper-ignore-next-stop
51    /// Adds @child_source to @self as a ‘polled’ source.
52    ///
53    /// When @self is added to a [`MainContext`][crate::MainContext], @child_source will be
54    /// automatically added with the same priority. When @child_source is triggered,
55    /// it will cause @self to dispatch (in addition to calling its own callback),
56    /// and when @self is destroyed, it will destroy @child_source as well.
57    ///
58    /// The @self will also still be dispatched if its own prepare/check functions
59    /// indicate that it is ready.
60    ///
61    /// If you don’t need @child_source to do anything on its own when it
62    /// triggers, you can call `g_source_set_dummy_callback()` on it to set a
63    /// callback that does nothing (except return true if appropriate).
64    ///
65    /// The @self will hold a reference on @child_source while @child_source
66    /// is attached to it.
67    ///
68    /// This API is only intended to be used by implementations of [`Source`][crate::Source].
69    /// Do not call this API on a [`Source`][crate::Source] that you did not create.
70    /// ## `child_source`
71    /// a second source that @self should ‘poll’
72    #[doc(alias = "g_source_add_child_source")]
73    pub fn add_child_source(&self, child_source: &Source) {
74        unsafe {
75            ffi::g_source_add_child_source(self.to_glib_none().0, child_source.to_glib_none().0);
76        }
77    }
78
79    //#[doc(alias = "g_source_add_poll")]
80    //pub fn add_poll(&self, fd: /*Ignored*/&mut PollFD) {
81    //    unsafe { TODO: call ffi:g_source_add_poll() }
82    //}
83
84    //#[doc(alias = "g_source_add_unix_fd")]
85    //pub fn add_unix_fd(&self, fd: i32, events: IOCondition) -> /*Unimplemented*/Basic: Pointer {
86    //    unsafe { TODO: call ffi:g_source_add_unix_fd() }
87    //}
88
89    #[doc(alias = "g_source_destroy")]
90    pub fn destroy(&self) {
91        unsafe {
92            ffi::g_source_destroy(self.to_glib_none().0);
93        }
94    }
95
96    /// Checks whether a source is allowed to be called recursively.
97    ///
98    /// See `GLib::Source::set_can_recurse()`.
99    ///
100    /// # Returns
101    ///
102    /// whether recursion is allowed
103    // rustdoc-stripper-ignore-next-stop
104    /// Checks whether a source is allowed to be called recursively.
105    ///
106    /// See `GLib::Source::set_can_recurse()`.
107    ///
108    /// # Returns
109    ///
110    /// whether recursion is allowed
111    #[doc(alias = "g_source_get_can_recurse")]
112    #[doc(alias = "get_can_recurse")]
113    pub fn can_recurse(&self) -> bool {
114        unsafe { from_glib(ffi::g_source_get_can_recurse(self.to_glib_none().0)) }
115    }
116
117    /// Gets a name for the source, used in debugging and profiling.
118    ///
119    /// The
120    /// name may be `NULL` if it has never been set with `GLib::Source::set_name()`.
121    ///
122    /// # Returns
123    ///
124    /// the name of the source
125    // rustdoc-stripper-ignore-next-stop
126    /// Gets a name for the source, used in debugging and profiling.
127    ///
128    /// The
129    /// name may be `NULL` if it has never been set with `GLib::Source::set_name()`.
130    ///
131    /// # Returns
132    ///
133    /// the name of the source
134    #[doc(alias = "g_source_get_name")]
135    #[doc(alias = "get_name")]
136    pub fn name(&self) -> Option<crate::GString> {
137        unsafe { from_glib_none(ffi::g_source_get_name(self.to_glib_none().0)) }
138    }
139
140    /// Gets the priority of a source.
141    ///
142    /// # Returns
143    ///
144    /// the priority of the source
145    // rustdoc-stripper-ignore-next-stop
146    /// Gets the priority of a source.
147    ///
148    /// # Returns
149    ///
150    /// the priority of the source
151    #[doc(alias = "g_source_get_priority")]
152    #[doc(alias = "get_priority")]
153    pub fn priority(&self) -> i32 {
154        unsafe { ffi::g_source_get_priority(self.to_glib_none().0) }
155    }
156
157    /// Gets the ‘ready time’ of @self, as set by
158    /// `GLib::Source::set_ready_time()`.
159    ///
160    /// Any time before or equal to the current monotonic time (including zero)
161    /// is an indication that the source will fire immediately.
162    ///
163    /// # Returns
164    ///
165    /// the monotonic ready time, `-1` for ‘never’
166    // rustdoc-stripper-ignore-next-stop
167    /// Gets the ‘ready time’ of @self, as set by
168    /// `GLib::Source::set_ready_time()`.
169    ///
170    /// Any time before or equal to the current monotonic time (including zero)
171    /// is an indication that the source will fire immediately.
172    ///
173    /// # Returns
174    ///
175    /// the monotonic ready time, `-1` for ‘never’
176    #[doc(alias = "g_source_get_ready_time")]
177    #[doc(alias = "get_ready_time")]
178    pub fn ready_time(&self) -> i64 {
179        unsafe { ffi::g_source_get_ready_time(self.to_glib_none().0) }
180    }
181
182    /// Gets the time to be used when checking this source.
183    ///
184    /// The advantage of
185    /// calling this function over calling [`monotonic_time()`][crate::monotonic_time()] directly is
186    /// that when checking multiple sources, GLib can cache a single value
187    /// instead of having to repeatedly get the system monotonic time.
188    ///
189    /// The time here is the system monotonic time, if available, or some
190    /// other reasonable alternative otherwise.  See [`monotonic_time()`][crate::monotonic_time()].
191    ///
192    /// # Returns
193    ///
194    /// the monotonic time in microseconds
195    // rustdoc-stripper-ignore-next-stop
196    /// Gets the time to be used when checking this source.
197    ///
198    /// The advantage of
199    /// calling this function over calling [`monotonic_time()`][crate::monotonic_time()] directly is
200    /// that when checking multiple sources, GLib can cache a single value
201    /// instead of having to repeatedly get the system monotonic time.
202    ///
203    /// The time here is the system monotonic time, if available, or some
204    /// other reasonable alternative otherwise.  See [`monotonic_time()`][crate::monotonic_time()].
205    ///
206    /// # Returns
207    ///
208    /// the monotonic time in microseconds
209    #[doc(alias = "g_source_get_time")]
210    #[doc(alias = "get_time")]
211    pub fn time(&self) -> i64 {
212        unsafe { ffi::g_source_get_time(self.to_glib_none().0) }
213    }
214
215    /// Returns whether @self has been destroyed.
216    ///
217    /// This is important when you operate upon your objects
218    /// from within idle handlers, but may have freed the object
219    /// before the dispatch of your idle handler.
220    ///
221    /// **⚠️ The following code is in c ⚠️**
222    ///
223    /// ```c
224    /// static gboolean
225    /// idle_callback (gpointer data)
226    /// {
227    ///   SomeWidget *self = data;
228    ///
229    ///   g_mutex_lock (&self->idle_id_mutex);
230    ///   // do stuff with self
231    ///   self->idle_id = 0;
232    ///   g_mutex_unlock (&self->idle_id_mutex);
233    ///
234    ///   return G_SOURCE_REMOVE;
235    /// }
236    ///
237    /// static void
238    /// some_widget_do_stuff_later (SomeWidget *self)
239    /// {
240    ///   g_mutex_lock (&self->idle_id_mutex);
241    ///   self->idle_id = g_idle_add (idle_callback, self);
242    ///   g_mutex_unlock (&self->idle_id_mutex);
243    /// }
244    ///
245    /// static void
246    /// some_widget_init (SomeWidget *self)
247    /// {
248    ///   g_mutex_init (&self->idle_id_mutex);
249    ///
250    ///   // ...
251    /// }
252    ///
253    /// static void
254    /// some_widget_finalize (GObject *object)
255    /// {
256    ///   SomeWidget *self = SOME_WIDGET (object);
257    ///
258    ///   if (self->idle_id)
259    ///     g_source_remove (self->idle_id);
260    ///
261    ///   g_mutex_clear (&self->idle_id_mutex);
262    ///
263    ///   G_OBJECT_CLASS (parent_class)->finalize (object);
264    /// }
265    /// ```
266    ///
267    /// This will fail in a multi-threaded application if the
268    /// widget is destroyed before the idle handler fires due
269    /// to the use after free in the callback. A solution, to
270    /// this particular problem, is to check to if the source
271    /// has already been destroy within the callback.
272    ///
273    /// **⚠️ The following code is in c ⚠️**
274    ///
275    /// ```c
276    /// static gboolean
277    /// idle_callback (gpointer data)
278    /// {
279    ///   SomeWidget *self = data;
280    ///
281    ///   g_mutex_lock (&self->idle_id_mutex);
282    ///   if (!g_source_is_destroyed (g_main_current_source ()))
283    ///     {
284    ///       // do stuff with self
285    ///     }
286    ///   g_mutex_unlock (&self->idle_id_mutex);
287    ///
288    ///   return FALSE;
289    /// }
290    /// ```
291    ///
292    /// Calls to this function from a thread other than the one acquired by the
293    /// [`MainContext`][crate::MainContext] the [`Source`][crate::Source] is attached to are typically
294    /// redundant, as the source could be destroyed immediately after this function
295    /// returns. However, once a source is destroyed it cannot be un-destroyed, so
296    /// this function can be used for opportunistic checks from any thread.
297    ///
298    /// # Returns
299    ///
300    /// true if the source has been destroyed, false otherwise
301    // rustdoc-stripper-ignore-next-stop
302    /// Returns whether @self has been destroyed.
303    ///
304    /// This is important when you operate upon your objects
305    /// from within idle handlers, but may have freed the object
306    /// before the dispatch of your idle handler.
307    ///
308    /// **⚠️ The following code is in c ⚠️**
309    ///
310    /// ```c
311    /// static gboolean
312    /// idle_callback (gpointer data)
313    /// {
314    ///   SomeWidget *self = data;
315    ///
316    ///   g_mutex_lock (&self->idle_id_mutex);
317    ///   // do stuff with self
318    ///   self->idle_id = 0;
319    ///   g_mutex_unlock (&self->idle_id_mutex);
320    ///
321    ///   return G_SOURCE_REMOVE;
322    /// }
323    ///
324    /// static void
325    /// some_widget_do_stuff_later (SomeWidget *self)
326    /// {
327    ///   g_mutex_lock (&self->idle_id_mutex);
328    ///   self->idle_id = g_idle_add (idle_callback, self);
329    ///   g_mutex_unlock (&self->idle_id_mutex);
330    /// }
331    ///
332    /// static void
333    /// some_widget_init (SomeWidget *self)
334    /// {
335    ///   g_mutex_init (&self->idle_id_mutex);
336    ///
337    ///   // ...
338    /// }
339    ///
340    /// static void
341    /// some_widget_finalize (GObject *object)
342    /// {
343    ///   SomeWidget *self = SOME_WIDGET (object);
344    ///
345    ///   if (self->idle_id)
346    ///     g_source_remove (self->idle_id);
347    ///
348    ///   g_mutex_clear (&self->idle_id_mutex);
349    ///
350    ///   G_OBJECT_CLASS (parent_class)->finalize (object);
351    /// }
352    /// ```
353    ///
354    /// This will fail in a multi-threaded application if the
355    /// widget is destroyed before the idle handler fires due
356    /// to the use after free in the callback. A solution, to
357    /// this particular problem, is to check to if the source
358    /// has already been destroy within the callback.
359    ///
360    /// **⚠️ The following code is in c ⚠️**
361    ///
362    /// ```c
363    /// static gboolean
364    /// idle_callback (gpointer data)
365    /// {
366    ///   SomeWidget *self = data;
367    ///
368    ///   g_mutex_lock (&self->idle_id_mutex);
369    ///   if (!g_source_is_destroyed (g_main_current_source ()))
370    ///     {
371    ///       // do stuff with self
372    ///     }
373    ///   g_mutex_unlock (&self->idle_id_mutex);
374    ///
375    ///   return FALSE;
376    /// }
377    /// ```
378    ///
379    /// Calls to this function from a thread other than the one acquired by the
380    /// [`MainContext`][crate::MainContext] the [`Source`][crate::Source] is attached to are typically
381    /// redundant, as the source could be destroyed immediately after this function
382    /// returns. However, once a source is destroyed it cannot be un-destroyed, so
383    /// this function can be used for opportunistic checks from any thread.
384    ///
385    /// # Returns
386    ///
387    /// true if the source has been destroyed, false otherwise
388    #[doc(alias = "g_source_is_destroyed")]
389    pub fn is_destroyed(&self) -> bool {
390        unsafe { from_glib(ffi::g_source_is_destroyed(self.to_glib_none().0)) }
391    }
392
393    //#[doc(alias = "g_source_modify_unix_fd")]
394    //pub fn modify_unix_fd(&self, tag: /*Unimplemented*/Basic: Pointer, new_events: IOCondition) {
395    //    unsafe { TODO: call ffi:g_source_modify_unix_fd() }
396    //}
397
398    //#[doc(alias = "g_source_query_unix_fd")]
399    //pub fn query_unix_fd(&self, tag: /*Unimplemented*/Basic: Pointer) -> IOCondition {
400    //    unsafe { TODO: call ffi:g_source_query_unix_fd() }
401    //}
402
403    /// Detaches @child_source from @self and destroys it.
404    ///
405    /// This API is only intended to be used by implementations of [`Source`][crate::Source].
406    /// Do not call this API on a [`Source`][crate::Source] that you did not create.
407    /// ## `child_source`
408    /// a source previously passed to
409    ///   [`add_child_source()`][Self::add_child_source()]
410    // rustdoc-stripper-ignore-next-stop
411    /// Detaches @child_source from @self and destroys it.
412    ///
413    /// This API is only intended to be used by implementations of [`Source`][crate::Source].
414    /// Do not call this API on a [`Source`][crate::Source] that you did not create.
415    /// ## `child_source`
416    /// a source previously passed to
417    ///   [`add_child_source()`][Self::add_child_source()]
418    #[doc(alias = "g_source_remove_child_source")]
419    pub fn remove_child_source(&self, child_source: &Source) {
420        unsafe {
421            ffi::g_source_remove_child_source(self.to_glib_none().0, child_source.to_glib_none().0);
422        }
423    }
424
425    //#[doc(alias = "g_source_remove_poll")]
426    //pub fn remove_poll(&self, fd: /*Ignored*/&mut PollFD) {
427    //    unsafe { TODO: call ffi:g_source_remove_poll() }
428    //}
429
430    //#[doc(alias = "g_source_remove_unix_fd")]
431    //pub fn remove_unix_fd(&self, tag: /*Unimplemented*/Basic: Pointer) {
432    //    unsafe { TODO: call ffi:g_source_remove_unix_fd() }
433    //}
434
435    //#[doc(alias = "g_source_remove_by_funcs_user_data")]
436    //pub fn remove_by_funcs_user_data(funcs: /*Ignored*/&mut SourceFuncs, user_data: /*Unimplemented*/Option<Basic: Pointer>) -> bool {
437    //    unsafe { TODO: call ffi:g_source_remove_by_funcs_user_data() }
438    //}
439
440    //#[doc(alias = "g_source_remove_by_user_data")]
441    //pub fn remove_by_user_data(user_data: /*Unimplemented*/Option<Basic: Pointer>) -> bool {
442    //    unsafe { TODO: call ffi:g_source_remove_by_user_data() }
443    //}
444}
445
446unsafe impl Send for Source {}
447unsafe impl Sync for Source {}