glib/auto/
main_context.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
5#[cfg(feature = "v2_72")]
6#[cfg_attr(docsrs, doc(cfg(feature = "v2_72")))]
7use crate::MainContextFlags;
8use crate::{ffi, translate::*};
9
10crate::wrapper! {
11    /// The `GMainContext` struct is an opaque data
12    /// type representing a set of sources to be handled in a main loop.
13    // rustdoc-stripper-ignore-next-stop
14    /// The `GMainContext` struct is an opaque data
15    /// type representing a set of sources to be handled in a main loop.
16    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
17    pub struct MainContext(Shared<ffi::GMainContext>);
18
19    match fn {
20        ref => |ptr| ffi::g_main_context_ref(ptr),
21        unref => |ptr| ffi::g_main_context_unref(ptr),
22        type_ => || ffi::g_main_context_get_type(),
23    }
24}
25
26impl MainContext {
27    /// Creates a new [`MainContext`][crate::MainContext] structure.
28    ///
29    /// # Returns
30    ///
31    /// the new #GMainContext
32    // rustdoc-stripper-ignore-next-stop
33    /// Creates a new [`MainContext`][crate::MainContext] structure.
34    ///
35    /// # Returns
36    ///
37    /// the new #GMainContext
38    #[doc(alias = "g_main_context_new")]
39    pub fn new() -> MainContext {
40        unsafe { from_glib_full(ffi::g_main_context_new()) }
41    }
42
43    /// Creates a new [`MainContext`][crate::MainContext] structure.
44    /// ## `flags`
45    /// a bitwise-OR combination of #GMainContextFlags flags that can only be
46    ///         set at creation time.
47    ///
48    /// # Returns
49    ///
50    /// the new #GMainContext
51    // rustdoc-stripper-ignore-next-stop
52    /// Creates a new [`MainContext`][crate::MainContext] structure.
53    /// ## `flags`
54    /// a bitwise-OR combination of #GMainContextFlags flags that can only be
55    ///         set at creation time.
56    ///
57    /// # Returns
58    ///
59    /// the new #GMainContext
60    #[cfg(feature = "v2_72")]
61    #[cfg_attr(docsrs, doc(cfg(feature = "v2_72")))]
62    #[doc(alias = "g_main_context_new_with_flags")]
63    #[doc(alias = "new_with_flags")]
64    pub fn with_flags(flags: MainContextFlags) -> MainContext {
65        unsafe { from_glib_full(ffi::g_main_context_new_with_flags(flags.into_glib())) }
66    }
67
68    //#[doc(alias = "g_main_context_add_poll")]
69    //pub fn add_poll(&self, fd: /*Ignored*/&mut PollFD, priority: i32) {
70    //    unsafe { TODO: call ffi:g_main_context_add_poll() }
71    //}
72
73    //#[doc(alias = "g_main_context_check")]
74    //pub fn check(&self, max_priority: i32, fds: /*Ignored*/&[PollFD]) -> bool {
75    //    unsafe { TODO: call ffi:g_main_context_check() }
76    //}
77
78    /// Dispatches all pending sources.
79    ///
80    /// You must have successfully acquired the context with
81    /// [`acquire()`][Self::acquire()] before you may call this function.
82    ///
83    /// Since 2.76 @self can be [`None`] to use the global-default
84    /// main context.
85    // rustdoc-stripper-ignore-next-stop
86    /// Dispatches all pending sources.
87    ///
88    /// You must have successfully acquired the context with
89    /// [`acquire()`][Self::acquire()] before you may call this function.
90    ///
91    /// Since 2.76 @self can be [`None`] to use the global-default
92    /// main context.
93    #[doc(alias = "g_main_context_dispatch")]
94    pub fn dispatch(&self) {
95        unsafe {
96            ffi::g_main_context_dispatch(self.to_glib_none().0);
97        }
98    }
99
100    //#[doc(alias = "g_main_context_find_source_by_funcs_user_data")]
101    //pub fn find_source_by_funcs_user_data(&self, funcs: /*Ignored*/&mut SourceFuncs, user_data: /*Unimplemented*/Option<Basic: Pointer>) -> Source {
102    //    unsafe { TODO: call ffi:g_main_context_find_source_by_funcs_user_data() }
103    //}
104
105    //#[doc(alias = "g_main_context_find_source_by_user_data")]
106    //pub fn find_source_by_user_data(&self, user_data: /*Unimplemented*/Option<Basic: Pointer>) -> Source {
107    //    unsafe { TODO: call ffi:g_main_context_find_source_by_user_data() }
108    //}
109
110    //#[doc(alias = "g_main_context_get_poll_func")]
111    //#[doc(alias = "get_poll_func")]
112    //pub fn poll_func(&self) -> /*Unimplemented*/Fn(/*Ignored*/PollFD, u32) -> i32 {
113    //    unsafe { TODO: call ffi:g_main_context_get_poll_func() }
114    //}
115
116    /// Determines whether this thread holds the (recursive)
117    /// ownership of this [`MainContext`][crate::MainContext]. This is useful to
118    /// know before waiting on another thread that may be
119    /// blocking to get ownership of @self.
120    ///
121    /// # Returns
122    ///
123    /// [`true`] if current thread is owner of @self.
124    // rustdoc-stripper-ignore-next-stop
125    /// Determines whether this thread holds the (recursive)
126    /// ownership of this [`MainContext`][crate::MainContext]. This is useful to
127    /// know before waiting on another thread that may be
128    /// blocking to get ownership of @self.
129    ///
130    /// # Returns
131    ///
132    /// [`true`] if current thread is owner of @self.
133    #[doc(alias = "g_main_context_is_owner")]
134    pub fn is_owner(&self) -> bool {
135        unsafe { from_glib(ffi::g_main_context_is_owner(self.to_glib_none().0)) }
136    }
137
138    /// Runs a single iteration for the given main loop. This involves
139    /// checking to see if any event sources are ready to be processed,
140    /// then if no events sources are ready and @may_block is [`true`], waiting
141    /// for a source to become ready, then dispatching the highest priority
142    /// events sources that are ready. Otherwise, if @may_block is [`false`]
143    /// sources are not waited to become ready, only those highest priority
144    /// events sources will be dispatched (if any), that are ready at this
145    /// given moment without further waiting.
146    ///
147    /// Note that even when @may_block is [`true`], it is still possible for
148    /// [`iteration()`][Self::iteration()] to return [`false`], since the wait may
149    /// be interrupted for other reasons than an event source becoming ready.
150    /// ## `may_block`
151    /// whether the call may block.
152    ///
153    /// # Returns
154    ///
155    /// [`true`] if events were dispatched.
156    // rustdoc-stripper-ignore-next-stop
157    /// Runs a single iteration for the given main loop. This involves
158    /// checking to see if any event sources are ready to be processed,
159    /// then if no events sources are ready and @may_block is [`true`], waiting
160    /// for a source to become ready, then dispatching the highest priority
161    /// events sources that are ready. Otherwise, if @may_block is [`false`]
162    /// sources are not waited to become ready, only those highest priority
163    /// events sources will be dispatched (if any), that are ready at this
164    /// given moment without further waiting.
165    ///
166    /// Note that even when @may_block is [`true`], it is still possible for
167    /// [`iteration()`][Self::iteration()] to return [`false`], since the wait may
168    /// be interrupted for other reasons than an event source becoming ready.
169    /// ## `may_block`
170    /// whether the call may block.
171    ///
172    /// # Returns
173    ///
174    /// [`true`] if events were dispatched.
175    #[doc(alias = "g_main_context_iteration")]
176    pub fn iteration(&self, may_block: bool) -> bool {
177        unsafe {
178            from_glib(ffi::g_main_context_iteration(
179                self.to_glib_none().0,
180                may_block.into_glib(),
181            ))
182        }
183    }
184
185    /// Checks if any sources have pending events for the given context.
186    ///
187    /// # Returns
188    ///
189    /// [`true`] if events are pending.
190    // rustdoc-stripper-ignore-next-stop
191    /// Checks if any sources have pending events for the given context.
192    ///
193    /// # Returns
194    ///
195    /// [`true`] if events are pending.
196    #[doc(alias = "g_main_context_pending")]
197    pub fn pending(&self) -> bool {
198        unsafe { from_glib(ffi::g_main_context_pending(self.to_glib_none().0)) }
199    }
200
201    //#[cfg(feature = "v2_64")]
202    //#[cfg_attr(docsrs, doc(cfg(feature = "v2_64")))]
203    //#[doc(alias = "g_main_context_pusher_new")]
204    //pub fn pusher_new(&self) -> /*Unknown conversion*//*Unimplemented*/MainContextPusher {
205    //    unsafe { TODO: call ffi:g_main_context_pusher_new() }
206    //}
207
208    //#[doc(alias = "g_main_context_query")]
209    //pub fn query(&self, max_priority: i32, fds: /*Ignored*/Vec<PollFD>) -> (i32, i32) {
210    //    unsafe { TODO: call ffi:g_main_context_query() }
211    //}
212
213    //#[doc(alias = "g_main_context_remove_poll")]
214    //pub fn remove_poll(&self, fd: /*Ignored*/&mut PollFD) {
215    //    unsafe { TODO: call ffi:g_main_context_remove_poll() }
216    //}
217
218    //#[doc(alias = "g_main_context_set_poll_func")]
219    //pub fn set_poll_func(&self, func: /*Unimplemented*/Fn(/*Ignored*/PollFD, u32) -> i32) {
220    //    unsafe { TODO: call ffi:g_main_context_set_poll_func() }
221    //}
222
223    //#[cfg_attr(feature = "v2_58", deprecated = "Since 2.58")]
224    //#[allow(deprecated)]
225    //#[doc(alias = "g_main_context_wait")]
226    //pub fn wait(&self, cond: /*Ignored*/&mut Cond, mutex: /*Ignored*/&mut Mutex) -> bool {
227    //    unsafe { TODO: call ffi:g_main_context_wait() }
228    //}
229
230    /// If @self is currently blocking in [`iteration()`][Self::iteration()]
231    /// waiting for a source to become ready, cause it to stop blocking
232    /// and return.  Otherwise, cause the next invocation of
233    /// [`iteration()`][Self::iteration()] to return without blocking.
234    ///
235    /// This API is useful for low-level control over [`MainContext`][crate::MainContext]; for
236    /// example, integrating it with main loop implementations such as
237    /// [`MainLoop`][crate::MainLoop].
238    ///
239    /// Another related use for this function is when implementing a main
240    /// loop with a termination condition, computed from multiple threads:
241    ///
242    ///
243    ///
244    /// **⚠️ The following code is in C ⚠️**
245    ///
246    /// ```C
247    ///   #define NUM_TASKS 10
248    ///   static gint tasks_remaining = NUM_TASKS;  // (atomic)
249    ///   ...
250    ///
251    ///   while (g_atomic_int_get (&tasks_remaining) != 0)
252    ///     g_main_context_iteration (NULL, TRUE);
253    /// ```
254    ///
255    /// Then in a thread:
256    ///
257    ///
258    /// **⚠️ The following code is in C ⚠️**
259    ///
260    /// ```C
261    ///   perform_work();
262    ///
263    ///   if (g_atomic_int_dec_and_test (&tasks_remaining))
264    ///     g_main_context_wakeup (NULL);
265    /// ```
266    // rustdoc-stripper-ignore-next-stop
267    /// If @self is currently blocking in [`iteration()`][Self::iteration()]
268    /// waiting for a source to become ready, cause it to stop blocking
269    /// and return.  Otherwise, cause the next invocation of
270    /// [`iteration()`][Self::iteration()] to return without blocking.
271    ///
272    /// This API is useful for low-level control over [`MainContext`][crate::MainContext]; for
273    /// example, integrating it with main loop implementations such as
274    /// [`MainLoop`][crate::MainLoop].
275    ///
276    /// Another related use for this function is when implementing a main
277    /// loop with a termination condition, computed from multiple threads:
278    ///
279    ///
280    ///
281    /// **⚠️ The following code is in C ⚠️**
282    ///
283    /// ```C
284    ///   #define NUM_TASKS 10
285    ///   static gint tasks_remaining = NUM_TASKS;  // (atomic)
286    ///   ...
287    ///
288    ///   while (g_atomic_int_get (&tasks_remaining) != 0)
289    ///     g_main_context_iteration (NULL, TRUE);
290    /// ```
291    ///
292    /// Then in a thread:
293    ///
294    ///
295    /// **⚠️ The following code is in C ⚠️**
296    ///
297    /// ```C
298    ///   perform_work();
299    ///
300    ///   if (g_atomic_int_dec_and_test (&tasks_remaining))
301    ///     g_main_context_wakeup (NULL);
302    /// ```
303    #[doc(alias = "g_main_context_wakeup")]
304    pub fn wakeup(&self) {
305        unsafe {
306            ffi::g_main_context_wakeup(self.to_glib_none().0);
307        }
308    }
309
310    /// Returns the global-default main context. This is the main context
311    /// used for main loop functions when a main loop is not explicitly
312    /// specified, and corresponds to the "main" main loop. See also
313    /// [`thread_default()`][Self::thread_default()].
314    ///
315    /// # Returns
316    ///
317    /// the global-default main context.
318    // rustdoc-stripper-ignore-next-stop
319    /// Returns the global-default main context. This is the main context
320    /// used for main loop functions when a main loop is not explicitly
321    /// specified, and corresponds to the "main" main loop. See also
322    /// [`thread_default()`][Self::thread_default()].
323    ///
324    /// # Returns
325    ///
326    /// the global-default main context.
327    #[doc(alias = "g_main_context_default")]
328    #[allow(clippy::should_implement_trait)]
329    pub fn default() -> MainContext {
330        unsafe { from_glib_none(ffi::g_main_context_default()) }
331    }
332
333    /// Gets the thread-default #GMainContext for this thread. Asynchronous
334    /// operations that want to be able to be run in contexts other than
335    /// the default one should call this method or
336    /// [`ref_thread_default()`][Self::ref_thread_default()] to get a
337    /// [`MainContext`][crate::MainContext] to add their [`Source`][crate::Source]s to. (Note that
338    /// even in single-threaded programs applications may sometimes want to
339    /// temporarily push a non-default context, so it is not safe to assume that
340    /// this will always return [`None`] if you are running in the default thread.)
341    ///
342    /// If you need to hold a reference on the context, use
343    /// [`ref_thread_default()`][Self::ref_thread_default()] instead.
344    ///
345    /// # Returns
346    ///
347    /// the thread-default #GMainContext, or
348    /// [`None`] if the thread-default context is the global-default main context.
349    // rustdoc-stripper-ignore-next-stop
350    /// Gets the thread-default #GMainContext for this thread. Asynchronous
351    /// operations that want to be able to be run in contexts other than
352    /// the default one should call this method or
353    /// [`ref_thread_default()`][Self::ref_thread_default()] to get a
354    /// [`MainContext`][crate::MainContext] to add their [`Source`][crate::Source]s to. (Note that
355    /// even in single-threaded programs applications may sometimes want to
356    /// temporarily push a non-default context, so it is not safe to assume that
357    /// this will always return [`None`] if you are running in the default thread.)
358    ///
359    /// If you need to hold a reference on the context, use
360    /// [`ref_thread_default()`][Self::ref_thread_default()] instead.
361    ///
362    /// # Returns
363    ///
364    /// the thread-default #GMainContext, or
365    /// [`None`] if the thread-default context is the global-default main context.
366    #[doc(alias = "g_main_context_get_thread_default")]
367    #[doc(alias = "get_thread_default")]
368    pub fn thread_default() -> Option<MainContext> {
369        unsafe { from_glib_none(ffi::g_main_context_get_thread_default()) }
370    }
371
372    //#[cfg(feature = "v2_64")]
373    //#[cfg_attr(docsrs, doc(cfg(feature = "v2_64")))]
374    //#[doc(alias = "g_main_context_pusher_free")]
375    //pub fn pusher_free(pusher: /*Unknown conversion*//*Unimplemented*/MainContextPusher) {
376    //    unsafe { TODO: call ffi:g_main_context_pusher_free() }
377    //}
378
379    /// Gets the thread-default [`MainContext`][crate::MainContext] for this thread, as with
380    /// [`thread_default()`][Self::thread_default()], but also adds a reference to
381    /// it with `GLib::MainContext::ref()`. In addition, unlike
382    /// [`thread_default()`][Self::thread_default()], if the thread-default context
383    /// is the global-default context, this will return that
384    /// [`MainContext`][crate::MainContext] (with a ref added to it) rather than returning
385    /// [`None`].
386    ///
387    /// # Returns
388    ///
389    /// the thread-default #GMainContext. Unref
390    ///     with `GLib::MainContext::unref()` when you are done with it.
391    // rustdoc-stripper-ignore-next-stop
392    /// Gets the thread-default [`MainContext`][crate::MainContext] for this thread, as with
393    /// [`thread_default()`][Self::thread_default()], but also adds a reference to
394    /// it with `GLib::MainContext::ref()`. In addition, unlike
395    /// [`thread_default()`][Self::thread_default()], if the thread-default context
396    /// is the global-default context, this will return that
397    /// [`MainContext`][crate::MainContext] (with a ref added to it) rather than returning
398    /// [`None`].
399    ///
400    /// # Returns
401    ///
402    /// the thread-default #GMainContext. Unref
403    ///     with `GLib::MainContext::unref()` when you are done with it.
404    #[doc(alias = "g_main_context_ref_thread_default")]
405    pub fn ref_thread_default() -> MainContext {
406        unsafe { from_glib_full(ffi::g_main_context_ref_thread_default()) }
407    }
408}
409
410impl Default for MainContext {
411    fn default() -> Self {
412        Self::new()
413    }
414}
415
416unsafe impl Send for MainContext {}
417unsafe impl Sync for MainContext {}