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