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    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
14    pub struct MainContext(Shared<ffi::GMainContext>);
15
16    match fn {
17        ref => |ptr| ffi::g_main_context_ref(ptr),
18        unref => |ptr| ffi::g_main_context_unref(ptr),
19        type_ => || ffi::g_main_context_get_type(),
20    }
21}
22
23impl MainContext {
24    /// Creates a new [`MainContext`][crate::MainContext] structure.
25    ///
26    /// # Returns
27    ///
28    /// the new main context
29    #[doc(alias = "g_main_context_new")]
30    pub fn new() -> MainContext {
31        unsafe { from_glib_full(ffi::g_main_context_new()) }
32    }
33
34    /// Creates a new [`MainContext`][crate::MainContext] structure.
35    /// ## `flags`
36    /// a bitwise-OR combination of flags that can only be set at creation
37    ///   time
38    ///
39    /// # Returns
40    ///
41    /// the new main context
42    #[cfg(feature = "v2_72")]
43    #[cfg_attr(docsrs, doc(cfg(feature = "v2_72")))]
44    #[doc(alias = "g_main_context_new_with_flags")]
45    #[doc(alias = "new_with_flags")]
46    pub fn with_flags(flags: MainContextFlags) -> MainContext {
47        unsafe { from_glib_full(ffi::g_main_context_new_with_flags(flags.into_glib())) }
48    }
49
50    //#[doc(alias = "g_main_context_add_poll")]
51    //pub fn add_poll(&self, fd: /*Ignored*/&mut PollFD, priority: i32) {
52    //    unsafe { TODO: call ffi:g_main_context_add_poll() }
53    //}
54
55    //#[doc(alias = "g_main_context_check")]
56    //pub fn check(&self, max_priority: i32, fds: /*Ignored*/&[PollFD]) -> bool {
57    //    unsafe { TODO: call ffi:g_main_context_check() }
58    //}
59
60    /// Dispatches all pending sources.
61    ///
62    /// You must have successfully acquired the context with
63    /// [`acquire()`][Self::acquire()] before you may call this function.
64    ///
65    /// Since 2.76 @self can be `NULL` to use the global-default
66    /// main context.
67    #[doc(alias = "g_main_context_dispatch")]
68    pub fn dispatch(&self) {
69        unsafe {
70            ffi::g_main_context_dispatch(self.to_glib_none().0);
71        }
72    }
73
74    //#[doc(alias = "g_main_context_find_source_by_funcs_user_data")]
75    //pub fn find_source_by_funcs_user_data(&self, funcs: /*Ignored*/&mut SourceFuncs, user_data: /*Unimplemented*/Option<Basic: Pointer>) -> Option<Source> {
76    //    unsafe { TODO: call ffi:g_main_context_find_source_by_funcs_user_data() }
77    //}
78
79    //#[doc(alias = "g_main_context_find_source_by_user_data")]
80    //pub fn find_source_by_user_data(&self, user_data: /*Unimplemented*/Option<Basic: Pointer>) -> Option<Source> {
81    //    unsafe { TODO: call ffi:g_main_context_find_source_by_user_data() }
82    //}
83
84    //#[doc(alias = "g_main_context_get_poll_func")]
85    //#[doc(alias = "get_poll_func")]
86    //pub fn poll_func(&self) -> /*Unimplemented*/Fn(/*Ignored*/PollFD, u32) -> i32 {
87    //    unsafe { TODO: call ffi:g_main_context_get_poll_func() }
88    //}
89
90    /// Determines whether this thread holds the (recursive)
91    /// ownership of this [`MainContext`][crate::MainContext].
92    ///
93    /// This is useful to
94    /// know before waiting on another thread that may be
95    /// blocking to get ownership of @self.
96    ///
97    /// # Returns
98    ///
99    /// true if current thread is owner of @self, false otherwise
100    #[doc(alias = "g_main_context_is_owner")]
101    pub fn is_owner(&self) -> bool {
102        unsafe { from_glib(ffi::g_main_context_is_owner(self.to_glib_none().0)) }
103    }
104
105    /// Runs a single iteration for the given main loop.
106    ///
107    /// This involves
108    /// checking to see if any event sources are ready to be processed,
109    /// then if no events sources are ready and @may_block is true, waiting
110    /// for a source to become ready, then dispatching the highest priority
111    /// events sources that are ready. Otherwise, if @may_block is false,
112    /// this function does not wait for sources to become ready, and only the highest
113    /// priority sources which are already ready (if any) will be dispatched.
114    ///
115    /// Note that even when @may_block is true, it is still possible for
116    /// [`iteration()`][Self::iteration()] to return false, since the wait may
117    /// be interrupted for other reasons than an event source becoming ready.
118    /// ## `may_block`
119    /// whether the call may block
120    ///
121    /// # Returns
122    ///
123    /// true if events were dispatched, false otherwise
124    #[doc(alias = "g_main_context_iteration")]
125    pub fn iteration(&self, may_block: bool) -> bool {
126        unsafe {
127            from_glib(ffi::g_main_context_iteration(
128                self.to_glib_none().0,
129                may_block.into_glib(),
130            ))
131        }
132    }
133
134    /// Checks if any sources have pending events for the given context.
135    ///
136    /// # Returns
137    ///
138    /// true if events are pending, false otherwise
139    #[doc(alias = "g_main_context_pending")]
140    pub fn pending(&self) -> bool {
141        unsafe { from_glib(ffi::g_main_context_pending(self.to_glib_none().0)) }
142    }
143
144    //#[cfg(feature = "v2_64")]
145    //#[cfg_attr(docsrs, doc(cfg(feature = "v2_64")))]
146    //#[doc(alias = "g_main_context_pusher_new")]
147    //pub fn pusher_new(&self) -> /*Unknown conversion*//*Unimplemented*/MainContextPusher {
148    //    unsafe { TODO: call ffi:g_main_context_pusher_new() }
149    //}
150
151    //#[doc(alias = "g_main_context_query")]
152    //pub fn query(&self, max_priority: i32, fds: /*Ignored*/Vec<PollFD>) -> (i32, i32) {
153    //    unsafe { TODO: call ffi:g_main_context_query() }
154    //}
155
156    //#[doc(alias = "g_main_context_remove_poll")]
157    //pub fn remove_poll(&self, fd: /*Ignored*/&mut PollFD) {
158    //    unsafe { TODO: call ffi:g_main_context_remove_poll() }
159    //}
160
161    //#[doc(alias = "g_main_context_set_poll_func")]
162    //pub fn set_poll_func(&self, func: /*Unimplemented*/Fn(/*Ignored*/PollFD, u32) -> i32) {
163    //    unsafe { TODO: call ffi:g_main_context_set_poll_func() }
164    //}
165
166    //#[cfg_attr(feature = "v2_58", deprecated = "Since 2.58")]
167    //#[allow(deprecated)]
168    //#[doc(alias = "g_main_context_wait")]
169    //pub fn wait(&self, cond: /*Ignored*/&mut Cond, mutex: /*Ignored*/&mut Mutex) -> bool {
170    //    unsafe { TODO: call ffi:g_main_context_wait() }
171    //}
172
173    /// Wake up @self if it’s currently blocking in
174    /// [`iteration()`][Self::iteration()], causing it to stop blocking.
175    ///
176    /// The @self could be blocking waiting for a source to become ready.
177    /// Otherwise, if @self is not currently blocking, this function causes the
178    /// next invocation of [`iteration()`][Self::iteration()] to return without
179    /// blocking.
180    ///
181    /// This API is useful for low-level control over [`MainContext`][crate::MainContext]; for
182    /// example, integrating it with main loop implementations such as
183    /// [`MainLoop`][crate::MainLoop].
184    ///
185    /// Another related use for this function is when implementing a main
186    /// loop with a termination condition, computed from multiple threads:
187    ///
188    /// **⚠️ The following code is in c ⚠️**
189    ///
190    /// ```c
191    ///   #define NUM_TASKS 10
192    ///   static gint tasks_remaining = NUM_TASKS;  // (atomic)
193    ///   ...
194    ///
195    ///   while (g_atomic_int_get (&tasks_remaining) != 0)
196    ///     g_main_context_iteration (NULL, TRUE);
197    /// ```
198    ///
199    /// Then in a thread:
200    /// **⚠️ The following code is in c ⚠️**
201    ///
202    /// ```c
203    ///   perform_work ();
204    ///
205    ///   if (g_atomic_int_dec_and_test (&tasks_remaining))
206    ///     g_main_context_wakeup (NULL);
207    /// ```
208    #[doc(alias = "g_main_context_wakeup")]
209    pub fn wakeup(&self) {
210        unsafe {
211            ffi::g_main_context_wakeup(self.to_glib_none().0);
212        }
213    }
214
215    /// Returns the global-default main context.
216    ///
217    /// This is the main context
218    /// used for main loop functions when a main loop is not explicitly
219    /// specified, and corresponds to the ‘main’ main loop. See also
220    /// [`thread_default()`][Self::thread_default()].
221    ///
222    /// # Returns
223    ///
224    /// the global-default main context.
225    #[doc(alias = "g_main_context_default")]
226    #[allow(clippy::should_implement_trait)]
227    pub fn default() -> MainContext {
228        unsafe { from_glib_none(ffi::g_main_context_default()) }
229    }
230
231    /// Gets the thread-default main context for this thread.
232    ///
233    /// Asynchronous operations that want to be able to be run in contexts other than
234    /// the default one should call this method or
235    /// [`ref_thread_default()`][Self::ref_thread_default()] to get a
236    /// [`MainContext`][crate::MainContext] to add their [`Source`][crate::Source]s to. (Note that
237    /// even in single-threaded programs applications may sometimes want to
238    /// temporarily push a non-default context, so it is not safe to assume that
239    /// this will always return `NULL` if you are running in the default thread.)
240    ///
241    /// If you need to hold a reference on the context, use
242    /// [`ref_thread_default()`][Self::ref_thread_default()] instead.
243    ///
244    /// # Returns
245    ///
246    /// the thread-default main context, or
247    ///   `NULL` if the thread-default context is the global-default main context
248    #[doc(alias = "g_main_context_get_thread_default")]
249    #[doc(alias = "get_thread_default")]
250    pub fn thread_default() -> Option<MainContext> {
251        unsafe { from_glib_none(ffi::g_main_context_get_thread_default()) }
252    }
253
254    //#[cfg(feature = "v2_64")]
255    //#[cfg_attr(docsrs, doc(cfg(feature = "v2_64")))]
256    //#[doc(alias = "g_main_context_pusher_free")]
257    //pub fn pusher_free(pusher: /*Unknown conversion*//*Unimplemented*/MainContextPusher) {
258    //    unsafe { TODO: call ffi:g_main_context_pusher_free() }
259    //}
260
261    /// Gets a reference to the thread-default [`MainContext`][crate::MainContext] for this
262    /// thread
263    ///
264    /// This is the same as [`thread_default()`][Self::thread_default()], but it also
265    /// adds a reference to the returned main context with `GLib::MainContext::ref()`.
266    /// In addition, unlike
267    /// [`thread_default()`][Self::thread_default()], if the thread-default context
268    /// is the global-default context, this will return that
269    /// [`MainContext`][crate::MainContext] (with a ref added to it) rather than returning
270    /// `NULL`.
271    ///
272    /// # Returns
273    ///
274    /// the thread-default main context
275    #[doc(alias = "g_main_context_ref_thread_default")]
276    pub fn ref_thread_default() -> MainContext {
277        unsafe { from_glib_full(ffi::g_main_context_ref_thread_default()) }
278    }
279}
280
281impl Default for MainContext {
282    fn default() -> Self {
283        Self::new()
284    }
285}
286
287unsafe impl Send for MainContext {}
288unsafe impl Sync for MainContext {}