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