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