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