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    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
11    pub struct Source(Shared<ffi::GSource>);
12
13    match fn {
14        ref => |ptr| ffi::g_source_ref(ptr),
15        unref => |ptr| ffi::g_source_unref(ptr),
16        type_ => || ffi::g_source_get_type(),
17    }
18}
19
20impl Source {
21    //#[doc(alias = "g_source_new")]
22    //pub fn new(source_funcs: /*Ignored*/&mut SourceFuncs, struct_size: u32) -> Source {
23    //    unsafe { TODO: call ffi:g_source_new() }
24    //}
25
26    /// Adds @child_source to @self as a "polled" source; when @self is
27    /// added to a [`MainContext`][crate::MainContext], @child_source will be automatically
28    /// added with the same priority, when @child_source is triggered, it will
29    /// cause @self to dispatch (in addition to calling its own
30    /// callback), and when @self is destroyed, it will destroy
31    /// @child_source as well. (@self will also still be dispatched if
32    /// its own prepare/check functions indicate that it is ready.)
33    ///
34    /// If you don't need @child_source to do anything on its own when it
35    /// triggers, you can call g_source_set_dummy_callback() on it to set a
36    /// callback that does nothing (except return [`true`] if appropriate).
37    ///
38    /// @self will hold a reference on @child_source while @child_source
39    /// is attached to it.
40    ///
41    /// This API is only intended to be used by implementations of
42    /// [`Source`][crate::Source]. Do not call this API on a [`Source`][crate::Source] that
43    /// you did not create.
44    /// ## `child_source`
45    /// a second #GSource that @self should "poll"
46    #[doc(alias = "g_source_add_child_source")]
47    pub fn add_child_source(&self, child_source: &Source) {
48        unsafe {
49            ffi::g_source_add_child_source(self.to_glib_none().0, child_source.to_glib_none().0);
50        }
51    }
52
53    //#[doc(alias = "g_source_add_poll")]
54    //pub fn add_poll(&self, fd: /*Ignored*/&mut PollFD) {
55    //    unsafe { TODO: call ffi:g_source_add_poll() }
56    //}
57
58    //#[doc(alias = "g_source_add_unix_fd")]
59    //pub fn add_unix_fd(&self, fd: i32, events: IOCondition) -> /*Unimplemented*/Basic: Pointer {
60    //    unsafe { TODO: call ffi:g_source_add_unix_fd() }
61    //}
62
63    #[doc(alias = "g_source_destroy")]
64    pub fn destroy(&self) {
65        unsafe {
66            ffi::g_source_destroy(self.to_glib_none().0);
67        }
68    }
69
70    /// Checks whether a source is allowed to be called recursively.
71    /// see `GLib::Source::set_can_recurse()`.
72    ///
73    /// # Returns
74    ///
75    /// whether recursion is allowed.
76    #[doc(alias = "g_source_get_can_recurse")]
77    #[doc(alias = "get_can_recurse")]
78    pub fn can_recurse(&self) -> bool {
79        unsafe { from_glib(ffi::g_source_get_can_recurse(self.to_glib_none().0)) }
80    }
81
82    /// Gets a name for the source, used in debugging and profiling.  The
83    /// name may be #NULL if it has never been set with `GLib::Source::set_name()`.
84    ///
85    /// # Returns
86    ///
87    /// the name of the source
88    #[doc(alias = "g_source_get_name")]
89    #[doc(alias = "get_name")]
90    pub fn name(&self) -> Option<crate::GString> {
91        unsafe { from_glib_none(ffi::g_source_get_name(self.to_glib_none().0)) }
92    }
93
94    /// Gets the priority of a source.
95    ///
96    /// # Returns
97    ///
98    /// the priority of the source
99    #[doc(alias = "g_source_get_priority")]
100    #[doc(alias = "get_priority")]
101    pub fn priority(&self) -> i32 {
102        unsafe { ffi::g_source_get_priority(self.to_glib_none().0) }
103    }
104
105    /// Gets the "ready time" of @self, as set by
106    /// `GLib::Source::set_ready_time()`.
107    ///
108    /// Any time before or equal to the current monotonic time (including 0)
109    /// is an indication that the source will fire immediately.
110    ///
111    /// # Returns
112    ///
113    /// the monotonic ready time, -1 for "never"
114    #[doc(alias = "g_source_get_ready_time")]
115    #[doc(alias = "get_ready_time")]
116    pub fn ready_time(&self) -> i64 {
117        unsafe { ffi::g_source_get_ready_time(self.to_glib_none().0) }
118    }
119
120    /// Gets the time to be used when checking this source. The advantage of
121    /// calling this function over calling [`monotonic_time()`][crate::monotonic_time()] directly is
122    /// that when checking multiple sources, GLib can cache a single value
123    /// instead of having to repeatedly get the system monotonic time.
124    ///
125    /// The time here is the system monotonic time, if available, or some
126    /// other reasonable alternative otherwise.  See [`monotonic_time()`][crate::monotonic_time()].
127    ///
128    /// # Returns
129    ///
130    /// the monotonic time in microseconds
131    #[doc(alias = "g_source_get_time")]
132    #[doc(alias = "get_time")]
133    pub fn time(&self) -> i64 {
134        unsafe { ffi::g_source_get_time(self.to_glib_none().0) }
135    }
136
137    /// Returns whether @self has been destroyed.
138    ///
139    /// This is important when you operate upon your objects
140    /// from within idle handlers, but may have freed the object
141    /// before the dispatch of your idle handler.
142    ///
143    ///
144    ///
145    /// **⚠️ The following code is in C ⚠️**
146    ///
147    /// ```C
148    /// static gboolean
149    /// idle_callback (gpointer data)
150    /// {
151    ///   SomeWidget *self = data;
152    ///
153    ///   g_mutex_lock (&self->idle_id_mutex);
154    ///   // do stuff with self
155    ///   self->idle_id = 0;
156    ///   g_mutex_unlock (&self->idle_id_mutex);
157    ///
158    ///   return G_SOURCE_REMOVE;
159    /// }
160    ///
161    /// static void
162    /// some_widget_do_stuff_later (SomeWidget *self)
163    /// {
164    ///   g_mutex_lock (&self->idle_id_mutex);
165    ///   self->idle_id = g_idle_add (idle_callback, self);
166    ///   g_mutex_unlock (&self->idle_id_mutex);
167    /// }
168    ///
169    /// static void
170    /// some_widget_init (SomeWidget *self)
171    /// {
172    ///   g_mutex_init (&self->idle_id_mutex);
173    ///
174    ///   // ...
175    /// }
176    ///
177    /// static void
178    /// some_widget_finalize (GObject *object)
179    /// {
180    ///   SomeWidget *self = SOME_WIDGET (object);
181    ///
182    ///   if (self->idle_id)
183    ///     g_source_remove (self->idle_id);
184    ///
185    ///   g_mutex_clear (&self->idle_id_mutex);
186    ///
187    ///   G_OBJECT_CLASS (parent_class)->finalize (object);
188    /// }
189    /// ```
190    ///
191    /// This will fail in a multi-threaded application if the
192    /// widget is destroyed before the idle handler fires due
193    /// to the use after free in the callback. A solution, to
194    /// this particular problem, is to check to if the source
195    /// has already been destroy within the callback.
196    ///
197    ///
198    ///
199    /// **⚠️ The following code is in C ⚠️**
200    ///
201    /// ```C
202    /// static gboolean
203    /// idle_callback (gpointer data)
204    /// {
205    ///   SomeWidget *self = data;
206    ///
207    ///   g_mutex_lock (&self->idle_id_mutex);
208    ///   if (!g_source_is_destroyed (g_main_current_source ()))
209    ///     {
210    ///       // do stuff with self
211    ///     }
212    ///   g_mutex_unlock (&self->idle_id_mutex);
213    ///
214    ///   return FALSE;
215    /// }
216    /// ```
217    ///
218    /// Calls to this function from a thread other than the one acquired by the
219    /// [`MainContext`][crate::MainContext] the #GSource is attached to are typically
220    /// redundant, as the source could be destroyed immediately after this function
221    /// returns. However, once a source is destroyed it cannot be un-destroyed, so
222    /// this function can be used for opportunistic checks from any thread.
223    ///
224    /// # Returns
225    ///
226    /// [`true`] if the source has been destroyed
227    #[doc(alias = "g_source_is_destroyed")]
228    pub fn is_destroyed(&self) -> bool {
229        unsafe { from_glib(ffi::g_source_is_destroyed(self.to_glib_none().0)) }
230    }
231
232    //#[doc(alias = "g_source_modify_unix_fd")]
233    //pub fn modify_unix_fd(&self, tag: /*Unimplemented*/Basic: Pointer, new_events: IOCondition) {
234    //    unsafe { TODO: call ffi:g_source_modify_unix_fd() }
235    //}
236
237    //#[doc(alias = "g_source_query_unix_fd")]
238    //pub fn query_unix_fd(&self, tag: /*Unimplemented*/Basic: Pointer) -> IOCondition {
239    //    unsafe { TODO: call ffi:g_source_query_unix_fd() }
240    //}
241
242    /// Detaches @child_source from @self and destroys it.
243    ///
244    /// This API is only intended to be used by implementations of #GSource.
245    /// Do not call this API on a #GSource that you did not create.
246    /// ## `child_source`
247    /// a #GSource previously passed to
248    ///     [`add_child_source()`][Self::add_child_source()].
249    #[doc(alias = "g_source_remove_child_source")]
250    pub fn remove_child_source(&self, child_source: &Source) {
251        unsafe {
252            ffi::g_source_remove_child_source(self.to_glib_none().0, child_source.to_glib_none().0);
253        }
254    }
255
256    //#[doc(alias = "g_source_remove_poll")]
257    //pub fn remove_poll(&self, fd: /*Ignored*/&mut PollFD) {
258    //    unsafe { TODO: call ffi:g_source_remove_poll() }
259    //}
260
261    //#[doc(alias = "g_source_remove_unix_fd")]
262    //pub fn remove_unix_fd(&self, tag: /*Unimplemented*/Basic: Pointer) {
263    //    unsafe { TODO: call ffi:g_source_remove_unix_fd() }
264    //}
265
266    //#[doc(alias = "g_source_remove_by_funcs_user_data")]
267    //pub fn remove_by_funcs_user_data(funcs: /*Ignored*/&mut SourceFuncs, user_data: /*Unimplemented*/Option<Basic: Pointer>) -> bool {
268    //    unsafe { TODO: call ffi:g_source_remove_by_funcs_user_data() }
269    //}
270
271    //#[doc(alias = "g_source_remove_by_user_data")]
272    //pub fn remove_by_user_data(user_data: /*Unimplemented*/Option<Basic: Pointer>) -> bool {
273    //    unsafe { TODO: call ffi:g_source_remove_by_user_data() }
274    //}
275}
276
277unsafe impl Send for Source {}
278unsafe impl Sync for Source {}