glib/auto/

main_context.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

#[cfg(feature = "v2_72")]
#[cfg_attr(docsrs, doc(cfg(feature = "v2_72")))]
use crate::MainContextFlags;
use crate::{ffi, translate::*};

crate::wrapper! {
    /// The `GMainContext` struct is an opaque data
    /// type representing a set of sources to be handled in a main loop.
    // rustdoc-stripper-ignore-next-stop
    /// The `GMainContext` struct is an opaque data
    /// type representing a set of sources to be handled in a main loop.
    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct MainContext(Shared<ffi::GMainContext>);

    match fn {
        ref => |ptr| ffi::g_main_context_ref(ptr),
        unref => |ptr| ffi::g_main_context_unref(ptr),
        type_ => || ffi::g_main_context_get_type(),
    }
}

impl MainContext {
    /// Creates a new [`MainContext`][crate::MainContext] structure.
    ///
    /// # Returns
    ///
    /// the new main context
    // rustdoc-stripper-ignore-next-stop
    /// Creates a new [`MainContext`][crate::MainContext] structure.
    ///
    /// # Returns
    ///
    /// the new main context
    #[doc(alias = "g_main_context_new")]
    pub fn new() -> MainContext {
        unsafe { from_glib_full(ffi::g_main_context_new()) }
    }

    /// Creates a new [`MainContext`][crate::MainContext] structure.
    /// ## `flags`
    /// a bitwise-OR combination of flags that can only be set at creation
    ///   time
    ///
    /// # Returns
    ///
    /// the new main context
    // rustdoc-stripper-ignore-next-stop
    /// Creates a new [`MainContext`][crate::MainContext] structure.
    /// ## `flags`
    /// a bitwise-OR combination of flags that can only be set at creation
    ///   time
    ///
    /// # Returns
    ///
    /// the new main context
    #[cfg(feature = "v2_72")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_72")))]
    #[doc(alias = "g_main_context_new_with_flags")]
    #[doc(alias = "new_with_flags")]
    pub fn with_flags(flags: MainContextFlags) -> MainContext {
        unsafe { from_glib_full(ffi::g_main_context_new_with_flags(flags.into_glib())) }
    }

    //#[doc(alias = "g_main_context_add_poll")]
    //pub fn add_poll(&self, fd: /*Ignored*/&mut PollFD, priority: i32) {
    //    unsafe { TODO: call ffi:g_main_context_add_poll() }
    //}

    //#[doc(alias = "g_main_context_check")]
    //pub fn check(&self, max_priority: i32, fds: /*Ignored*/&[PollFD]) -> bool {
    //    unsafe { TODO: call ffi:g_main_context_check() }
    //}

    /// Dispatches all pending sources.
    ///
    /// You must have successfully acquired the context with
    /// [`acquire()`][Self::acquire()] before you may call this function.
    ///
    /// Since 2.76 @self can be `NULL` to use the global-default
    /// main context.
    // rustdoc-stripper-ignore-next-stop
    /// Dispatches all pending sources.
    ///
    /// You must have successfully acquired the context with
    /// [`acquire()`][Self::acquire()] before you may call this function.
    ///
    /// Since 2.76 @self can be `NULL` to use the global-default
    /// main context.
    #[doc(alias = "g_main_context_dispatch")]
    pub fn dispatch(&self) {
        unsafe {
            ffi::g_main_context_dispatch(self.to_glib_none().0);
        }
    }

    //#[doc(alias = "g_main_context_find_source_by_funcs_user_data")]
    //pub fn find_source_by_funcs_user_data(&self, funcs: /*Ignored*/&mut SourceFuncs, user_data: /*Unimplemented*/Option<Basic: Pointer>) -> Option<Source> {
    //    unsafe { TODO: call ffi:g_main_context_find_source_by_funcs_user_data() }
    //}

    //#[doc(alias = "g_main_context_find_source_by_user_data")]
    //pub fn find_source_by_user_data(&self, user_data: /*Unimplemented*/Option<Basic: Pointer>) -> Option<Source> {
    //    unsafe { TODO: call ffi:g_main_context_find_source_by_user_data() }
    //}

    //#[doc(alias = "g_main_context_get_poll_func")]
    //#[doc(alias = "get_poll_func")]
    //pub fn poll_func(&self) -> /*Unimplemented*/Fn(/*Ignored*/PollFD, u32) -> i32 {
    //    unsafe { TODO: call ffi:g_main_context_get_poll_func() }
    //}

    /// Determines whether this thread holds the (recursive)
    /// ownership of this [`MainContext`][crate::MainContext].
    ///
    /// This is useful to
    /// know before waiting on another thread that may be
    /// blocking to get ownership of @self.
    ///
    /// # Returns
    ///
    /// true if current thread is owner of @self, false otherwise
    // rustdoc-stripper-ignore-next-stop
    /// Determines whether this thread holds the (recursive)
    /// ownership of this [`MainContext`][crate::MainContext].
    ///
    /// This is useful to
    /// know before waiting on another thread that may be
    /// blocking to get ownership of @self.
    ///
    /// # Returns
    ///
    /// true if current thread is owner of @self, false otherwise
    #[doc(alias = "g_main_context_is_owner")]
    pub fn is_owner(&self) -> bool {
        unsafe { from_glib(ffi::g_main_context_is_owner(self.to_glib_none().0)) }
    }

    /// Runs a single iteration for the given main loop.
    ///
    /// This involves
    /// checking to see if any event sources are ready to be processed,
    /// then if no events sources are ready and @may_block is true, waiting
    /// for a source to become ready, then dispatching the highest priority
    /// events sources that are ready. Otherwise, if @may_block is false,
    /// this function does not wait for sources to become ready, and only the highest
    /// priority sources which are already ready (if any) will be dispatched.
    ///
    /// Note that even when @may_block is true, it is still possible for
    /// [`iteration()`][Self::iteration()] to return false, since the wait may
    /// be interrupted for other reasons than an event source becoming ready.
    /// ## `may_block`
    /// whether the call may block
    ///
    /// # Returns
    ///
    /// true if events were dispatched, false otherwise
    // rustdoc-stripper-ignore-next-stop
    /// Runs a single iteration for the given main loop.
    ///
    /// This involves
    /// checking to see if any event sources are ready to be processed,
    /// then if no events sources are ready and @may_block is true, waiting
    /// for a source to become ready, then dispatching the highest priority
    /// events sources that are ready. Otherwise, if @may_block is false,
    /// this function does not wait for sources to become ready, and only the highest
    /// priority sources which are already ready (if any) will be dispatched.
    ///
    /// Note that even when @may_block is true, it is still possible for
    /// [`iteration()`][Self::iteration()] to return false, since the wait may
    /// be interrupted for other reasons than an event source becoming ready.
    /// ## `may_block`
    /// whether the call may block
    ///
    /// # Returns
    ///
    /// true if events were dispatched, false otherwise
    #[doc(alias = "g_main_context_iteration")]
    pub fn iteration(&self, may_block: bool) -> bool {
        unsafe {
            from_glib(ffi::g_main_context_iteration(
                self.to_glib_none().0,
                may_block.into_glib(),
            ))
        }
    }

    /// Checks if any sources have pending events for the given context.
    ///
    /// # Returns
    ///
    /// true if events are pending, false otherwise
    // rustdoc-stripper-ignore-next-stop
    /// Checks if any sources have pending events for the given context.
    ///
    /// # Returns
    ///
    /// true if events are pending, false otherwise
    #[doc(alias = "g_main_context_pending")]
    pub fn pending(&self) -> bool {
        unsafe { from_glib(ffi::g_main_context_pending(self.to_glib_none().0)) }
    }

    //#[cfg(feature = "v2_64")]
    //#[cfg_attr(docsrs, doc(cfg(feature = "v2_64")))]
    //#[doc(alias = "g_main_context_pusher_new")]
    //pub fn pusher_new(&self) -> /*Unknown conversion*//*Unimplemented*/MainContextPusher {
    //    unsafe { TODO: call ffi:g_main_context_pusher_new() }
    //}

    //#[doc(alias = "g_main_context_query")]
    //pub fn query(&self, max_priority: i32, fds: /*Ignored*/Vec<PollFD>) -> (i32, i32) {
    //    unsafe { TODO: call ffi:g_main_context_query() }
    //}

    //#[doc(alias = "g_main_context_remove_poll")]
    //pub fn remove_poll(&self, fd: /*Ignored*/&mut PollFD) {
    //    unsafe { TODO: call ffi:g_main_context_remove_poll() }
    //}

    //#[doc(alias = "g_main_context_set_poll_func")]
    //pub fn set_poll_func(&self, func: /*Unimplemented*/Fn(/*Ignored*/PollFD, u32) -> i32) {
    //    unsafe { TODO: call ffi:g_main_context_set_poll_func() }
    //}

    //#[cfg_attr(feature = "v2_58", deprecated = "Since 2.58")]
    //#[allow(deprecated)]
    //#[doc(alias = "g_main_context_wait")]
    //pub fn wait(&self, cond: /*Ignored*/&mut Cond, mutex: /*Ignored*/&mut Mutex) -> bool {
    //    unsafe { TODO: call ffi:g_main_context_wait() }
    //}

    /// Wake up @self if it’s currently blocking in
    /// [`iteration()`][Self::iteration()], causing it to stop blocking.
    ///
    /// The @self could be blocking waiting for a source to become ready.
    /// Otherwise, if @self is not currently blocking, this function causes the
    /// next invocation of [`iteration()`][Self::iteration()] to return without
    /// blocking.
    ///
    /// This API is useful for low-level control over [`MainContext`][crate::MainContext]; for
    /// example, integrating it with main loop implementations such as
    /// [`MainLoop`][crate::MainLoop].
    ///
    /// Another related use for this function is when implementing a main
    /// loop with a termination condition, computed from multiple threads:
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    ///   #define NUM_TASKS 10
    ///   static gint tasks_remaining = NUM_TASKS;  // (atomic)
    ///   ...
    ///
    ///   while (g_atomic_int_get (&tasks_remaining) != 0)
    ///     g_main_context_iteration (NULL, TRUE);
    /// ```
    ///
    /// Then in a thread:
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    ///   perform_work ();
    ///
    ///   if (g_atomic_int_dec_and_test (&tasks_remaining))
    ///     g_main_context_wakeup (NULL);
    /// ```
    // rustdoc-stripper-ignore-next-stop
    /// Wake up @self if it’s currently blocking in
    /// [`iteration()`][Self::iteration()], causing it to stop blocking.
    ///
    /// The @self could be blocking waiting for a source to become ready.
    /// Otherwise, if @self is not currently blocking, this function causes the
    /// next invocation of [`iteration()`][Self::iteration()] to return without
    /// blocking.
    ///
    /// This API is useful for low-level control over [`MainContext`][crate::MainContext]; for
    /// example, integrating it with main loop implementations such as
    /// [`MainLoop`][crate::MainLoop].
    ///
    /// Another related use for this function is when implementing a main
    /// loop with a termination condition, computed from multiple threads:
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    ///   #define NUM_TASKS 10
    ///   static gint tasks_remaining = NUM_TASKS;  // (atomic)
    ///   ...
    ///
    ///   while (g_atomic_int_get (&tasks_remaining) != 0)
    ///     g_main_context_iteration (NULL, TRUE);
    /// ```
    ///
    /// Then in a thread:
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    ///   perform_work ();
    ///
    ///   if (g_atomic_int_dec_and_test (&tasks_remaining))
    ///     g_main_context_wakeup (NULL);
    /// ```
    #[doc(alias = "g_main_context_wakeup")]
    pub fn wakeup(&self) {
        unsafe {
            ffi::g_main_context_wakeup(self.to_glib_none().0);
        }
    }

    /// Returns the global-default main context.
    ///
    /// This is the main context
    /// used for main loop functions when a main loop is not explicitly
    /// specified, and corresponds to the ‘main’ main loop. See also
    /// [`thread_default()`][Self::thread_default()].
    ///
    /// # Returns
    ///
    /// the global-default main context.
    // rustdoc-stripper-ignore-next-stop
    /// Returns the global-default main context.
    ///
    /// This is the main context
    /// used for main loop functions when a main loop is not explicitly
    /// specified, and corresponds to the ‘main’ main loop. See also
    /// [`thread_default()`][Self::thread_default()].
    ///
    /// # Returns
    ///
    /// the global-default main context.
    #[doc(alias = "g_main_context_default")]
    #[allow(clippy::should_implement_trait)]
    pub fn default() -> MainContext {
        unsafe { from_glib_none(ffi::g_main_context_default()) }
    }

    /// Gets the thread-default main context for this thread.
    ///
    /// Asynchronous operations that want to be able to be run in contexts other than
    /// the default one should call this method or
    /// [`ref_thread_default()`][Self::ref_thread_default()] to get a
    /// [`MainContext`][crate::MainContext] to add their [`Source`][crate::Source]s to. (Note that
    /// even in single-threaded programs applications may sometimes want to
    /// temporarily push a non-default context, so it is not safe to assume that
    /// this will always return `NULL` if you are running in the default thread.)
    ///
    /// If you need to hold a reference on the context, use
    /// [`ref_thread_default()`][Self::ref_thread_default()] instead.
    ///
    /// # Returns
    ///
    /// the thread-default main context, or
    ///   `NULL` if the thread-default context is the global-default main context
    // rustdoc-stripper-ignore-next-stop
    /// Gets the thread-default main context for this thread.
    ///
    /// Asynchronous operations that want to be able to be run in contexts other than
    /// the default one should call this method or
    /// [`ref_thread_default()`][Self::ref_thread_default()] to get a
    /// [`MainContext`][crate::MainContext] to add their [`Source`][crate::Source]s to. (Note that
    /// even in single-threaded programs applications may sometimes want to
    /// temporarily push a non-default context, so it is not safe to assume that
    /// this will always return `NULL` if you are running in the default thread.)
    ///
    /// If you need to hold a reference on the context, use
    /// [`ref_thread_default()`][Self::ref_thread_default()] instead.
    ///
    /// # Returns
    ///
    /// the thread-default main context, or
    ///   `NULL` if the thread-default context is the global-default main context
    #[doc(alias = "g_main_context_get_thread_default")]
    #[doc(alias = "get_thread_default")]
    pub fn thread_default() -> Option<MainContext> {
        unsafe { from_glib_none(ffi::g_main_context_get_thread_default()) }
    }

    //#[cfg(feature = "v2_64")]
    //#[cfg_attr(docsrs, doc(cfg(feature = "v2_64")))]
    //#[doc(alias = "g_main_context_pusher_free")]
    //pub fn pusher_free(pusher: /*Unknown conversion*//*Unimplemented*/MainContextPusher) {
    //    unsafe { TODO: call ffi:g_main_context_pusher_free() }
    //}

    /// Gets a reference to the thread-default [`MainContext`][crate::MainContext] for this
    /// thread
    ///
    /// This is the same as [`thread_default()`][Self::thread_default()], but it also
    /// adds a reference to the returned main context with `GLib::MainContext::ref()`.
    /// In addition, unlike
    /// [`thread_default()`][Self::thread_default()], if the thread-default context
    /// is the global-default context, this will return that
    /// [`MainContext`][crate::MainContext] (with a ref added to it) rather than returning
    /// `NULL`.
    ///
    /// # Returns
    ///
    /// the thread-default main context
    // rustdoc-stripper-ignore-next-stop
    /// Gets a reference to the thread-default [`MainContext`][crate::MainContext] for this
    /// thread
    ///
    /// This is the same as [`thread_default()`][Self::thread_default()], but it also
    /// adds a reference to the returned main context with `GLib::MainContext::ref()`.
    /// In addition, unlike
    /// [`thread_default()`][Self::thread_default()], if the thread-default context
    /// is the global-default context, this will return that
    /// [`MainContext`][crate::MainContext] (with a ref added to it) rather than returning
    /// `NULL`.
    ///
    /// # Returns
    ///
    /// the thread-default main context
    #[doc(alias = "g_main_context_ref_thread_default")]
    pub fn ref_thread_default() -> MainContext {
        unsafe { from_glib_full(ffi::g_main_context_ref_thread_default()) }
    }
}

impl Default for MainContext {
    fn default() -> Self {
        Self::new()
    }
}

unsafe impl Send for MainContext {}
unsafe impl Sync for MainContext {}