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