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