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