glib/

main_context.rs

// Take a look at the license at the top of the repository in the LICENSE file.

use std::mem;

use crate::ffi::{self, gboolean, gpointer};

use crate::{MainContext, Source, SourceId, source::Priority, translate::*};

impl MainContext {
    /// Prepares to poll sources within a main loop.
    ///
    /// The resulting information
    /// for polling is determined by calling `GLib::MainContext::query()`.
    ///
    /// You must have successfully acquired the context with
    /// [`acquire()`][Self::acquire()] before you may call this function.
    ///
    /// # Returns
    ///
    /// true if some source is ready to be dispatched prior to polling,
    ///   false otherwise
    ///
    /// ## `priority`
    /// location to store priority of highest priority
    ///   source already ready
    // rustdoc-stripper-ignore-next-stop
    /// Prepares to poll sources within a main loop.
    ///
    /// The resulting information
    /// for polling is determined by calling `GLib::MainContext::query()`.
    ///
    /// You must have successfully acquired the context with
    /// [`acquire()`][Self::acquire()] before you may call this function.
    ///
    /// # Returns
    ///
    /// true if some source is ready to be dispatched prior to polling,
    ///   false otherwise
    ///
    /// ## `priority`
    /// location to store priority of highest priority
    ///   source already ready
    #[doc(alias = "g_main_context_prepare")]
    pub fn prepare(&self) -> (bool, i32) {
        unsafe {
            let mut priority = mem::MaybeUninit::uninit();

            let res = from_glib(ffi::g_main_context_prepare(
                self.to_glib_none().0,
                priority.as_mut_ptr(),
            ));
            let priority = priority.assume_init();
            (res, priority)
        }
    }

    /// Finds a [`Source`][crate::Source] given a pair of context and ID.
    ///
    /// It is a programmer error to attempt to look up a non-existent source.
    ///
    /// More specifically: source IDs can be reissued after a source has been
    /// destroyed and therefore it is never valid to use this function with a
    /// source ID which may have already been removed.  An example is when
    /// scheduling an idle to run in another thread with `idle_add()`: the
    /// idle may already have run and been removed by the time this function
    /// is called on its (now invalid) source ID.  This source ID may have
    /// been reissued, leading to the operation being performed against the
    /// wrong source.
    /// ## `source_id`
    /// the source ID, as returned by `GLib::Source::get_id()`
    ///
    /// # Returns
    ///
    /// the source
    // rustdoc-stripper-ignore-next-stop
    /// Finds a [`Source`][crate::Source] given a pair of context and ID.
    ///
    /// It is a programmer error to attempt to look up a non-existent source.
    ///
    /// More specifically: source IDs can be reissued after a source has been
    /// destroyed and therefore it is never valid to use this function with a
    /// source ID which may have already been removed.  An example is when
    /// scheduling an idle to run in another thread with `idle_add()`: the
    /// idle may already have run and been removed by the time this function
    /// is called on its (now invalid) source ID.  This source ID may have
    /// been reissued, leading to the operation being performed against the
    /// wrong source.
    /// ## `source_id`
    /// the source ID, as returned by `GLib::Source::get_id()`
    ///
    /// # Returns
    ///
    /// the source
    #[doc(alias = "g_main_context_find_source_by_id")]
    pub fn find_source_by_id(&self, source_id: &SourceId) -> Option<Source> {
        unsafe {
            from_glib_none(ffi::g_main_context_find_source_by_id(
                self.to_glib_none().0,
                source_id.as_raw(),
            ))
        }
    }

    // rustdoc-stripper-ignore-next
    /// Invokes `func` on the main context.
    ///
    /// If the current thread is the owner of the main context or the main context currently has no
    /// owner then `func` will be called directly from inside this function. If this behaviour is
    /// not desired and `func` should always be called asynchronously then use [`MainContext::spawn`]
    /// [`glib::idle_add`](crate::idle_add) instead.
    // rustdoc-stripper-ignore-next-stop
    /// Invokes a function in such a way that @self is owned during the
    /// invocation of @function.
    ///
    /// If @self is `NULL` then the global-default main context — as
    /// returned by [`default()`][Self::default()] — is used.
    ///
    /// If @self is owned by the current thread, @function is called
    /// directly.  Otherwise, if @self is the thread-default main context
    /// of the current thread and [`acquire()`][Self::acquire()] succeeds,
    /// then @function is called and [`release()`][Self::release()] is called
    /// afterwards.
    ///
    /// In any other case, an idle source is created to call @function and
    /// that source is attached to @self (presumably to be run in another
    /// thread).  The idle source is attached with `GLib::PRIORITY_DEFAULT`
    /// priority.  If you want a different priority, use
    /// [`invoke_full()`][Self::invoke_full()].
    ///
    /// Note that, as with normal idle functions, @function should probably return
    /// `GLib::SOURCE_REMOVE`.  If it returns `GLib::SOURCE_CONTINUE`, it
    /// will be continuously run in a loop (and may prevent this call from returning).
    /// ## `function`
    /// function to call
    // rustdoc-stripper-ignore-next-stop
    /// Invokes a function in such a way that @self is owned during the
    /// invocation of @function.
    ///
    /// If @self is `NULL` then the global-default main context — as
    /// returned by [`default()`][Self::default()] — is used.
    ///
    /// If @self is owned by the current thread, @function is called
    /// directly.  Otherwise, if @self is the thread-default main context
    /// of the current thread and [`acquire()`][Self::acquire()] succeeds,
    /// then @function is called and [`release()`][Self::release()] is called
    /// afterwards.
    ///
    /// In any other case, an idle source is created to call @function and
    /// that source is attached to @self (presumably to be run in another
    /// thread).  The idle source is attached with `GLib::PRIORITY_DEFAULT`
    /// priority.  If you want a different priority, use
    /// [`invoke_full()`][Self::invoke_full()].
    ///
    /// Note that, as with normal idle functions, @function should probably return
    /// `GLib::SOURCE_REMOVE`.  If it returns `GLib::SOURCE_CONTINUE`, it
    /// will be continuously run in a loop (and may prevent this call from returning).
    /// ## `function`
    /// function to call
    #[doc(alias = "g_main_context_invoke")]
    pub fn invoke<F>(&self, func: F)
    where
        F: FnOnce() + Send + 'static,
    {
        self.invoke_with_priority(crate::Priority::DEFAULT_IDLE, func);
    }

    // rustdoc-stripper-ignore-next
    /// Invokes `func` on the main context with the given priority.
    ///
    /// If the current thread is the owner of the main context or the main context currently has no
    /// owner then `func` will be called directly from inside this function. If this behaviour is
    /// not desired and `func` should always be called asynchronously then use [`MainContext::spawn`]
    /// [`glib::idle_add`](crate::idle_add) instead.
    #[doc(alias = "g_main_context_invoke_full")]
    pub fn invoke_with_priority<F>(&self, priority: Priority, func: F)
    where
        F: FnOnce() + Send + 'static,
    {
        unsafe {
            self.invoke_unsafe(priority, func);
        }
    }

    // rustdoc-stripper-ignore-next
    /// Invokes `func` on the main context.
    ///
    /// Different to `invoke()`, this does not require `func` to be
    /// `Send` but can only be called from the thread that owns the main context.
    ///
    /// This function panics if called from a different thread than the one that
    /// owns the main context.
    ///
    /// Note that this effectively means that `func` is called directly from inside this function
    /// or otherwise panics immediately. If this behaviour is not desired and `func` should always
    /// be called asynchronously then use [`MainContext::spawn_local`]
    /// [`glib::idle_add_local`](crate::idle_add_local) instead.
    pub fn invoke_local<F>(&self, func: F)
    where
        F: FnOnce() + 'static,
    {
        self.invoke_local_with_priority(crate::Priority::DEFAULT_IDLE, func);
    }

    // rustdoc-stripper-ignore-next
    /// Invokes `func` on the main context with the given priority.
    ///
    /// Different to `invoke_with_priority()`, this does not require `func` to be
    /// `Send` but can only be called from the thread that owns the main context.
    ///
    /// This function panics if called from a different thread than the one that
    /// owns the main context.
    ///
    /// Note that this effectively means that `func` is called directly from inside this function
    /// or otherwise panics immediately. If this behaviour is not desired and `func` should always
    /// be called asynchronously then use [`MainContext::spawn_local`]
    /// [`glib::idle_add_local`](crate::idle_add_local) instead.
    #[allow(clippy::if_same_then_else)]
    pub fn invoke_local_with_priority<F>(&self, _priority: Priority, func: F)
    where
        F: FnOnce() + 'static,
    {
        // Checks from `g_main_context_invoke_full()`
        // FIXME: Combine the first two cases somehow
        if self.is_owner() {
            func();
        } else {
            match self.acquire() {
                Ok(_acquire) => {
                    func();
                }
                _ => {
                    panic!("Must be called from a thread that owns the main context");
                }
            }
        }
    }

    unsafe fn invoke_unsafe<F>(&self, priority: Priority, func: F)
    where
        F: FnOnce() + 'static,
    {
        unsafe {
            unsafe extern "C" fn trampoline<F: FnOnce() + 'static>(func: gpointer) -> gboolean {
                unsafe {
                    let func: &mut Option<F> = &mut *(func as *mut Option<F>);
                    let func = func
                        .take()
                        .expect("MainContext::invoke() closure called multiple times");
                    func();
                    ffi::G_SOURCE_REMOVE
                }
            }
            unsafe extern "C" fn destroy_closure<F: FnOnce() + 'static>(ptr: gpointer) {
                unsafe {
                    let _ = Box::<Option<F>>::from_raw(ptr as *mut _);
                }
            }
            let func = Box::into_raw(Box::new(Some(func)));
            ffi::g_main_context_invoke_full(
                self.to_glib_none().0,
                priority.into_glib(),
                Some(trampoline::<F>),
                func as gpointer,
                Some(destroy_closure::<F>),
            )
        }
    }

    // rustdoc-stripper-ignore-next
    /// Call closure with the main context configured as the thread default one.
    ///
    /// The thread default main context is changed in a panic-safe manner before calling `func` and
    /// released again afterwards regardless of whether closure panicked or not.
    ///
    /// This will fail if the main context is owned already by another thread.
    // rustdoc-stripper-ignore-next-stop
    /// Acquires @self and sets it as the thread-default context for the
    /// current thread. This will cause certain asynchronous operations
    /// (such as most [Gio](../gio/index.html)-based I/O) which are
    /// started in this thread to run under @self and deliver their
    /// results to its main loop, rather than running under the global
    /// default main context in the main thread. Note that calling this function
    /// changes the context returned by [`thread_default()`][Self::thread_default()],
    /// not the one returned by [`default()`][Self::default()], so it does not
    /// affect the context used by functions like `idle_add()`.
    ///
    /// Normally you would call this function shortly after creating a new
    /// thread, passing it a [`MainContext`][crate::MainContext] which will be run by a
    /// [`MainLoop`][crate::MainLoop] in that thread, to set a new default context for all
    /// async operations in that thread. In this case you may not need to
    /// ever call [`pop_thread_default()`][Self::pop_thread_default()], assuming you want
    /// the new [`MainContext`][crate::MainContext] to be the default for the whole lifecycle
    /// of the thread.
    ///
    /// If you don’t have control over how the new thread was created (e.g.
    /// in the new thread isn’t newly created, or if the thread life
    /// cycle is managed by a #GThreadPool), it is always suggested to wrap
    /// the logic that needs to use the new [`MainContext`][crate::MainContext] inside a
    /// [`with_thread_default()`][Self::with_thread_default()] /
    /// [`pop_thread_default()`][Self::pop_thread_default()] pair, otherwise threads that
    /// are re-used will end up never explicitly releasing the
    /// [`MainContext`][crate::MainContext] reference they hold.
    ///
    /// In some cases you may want to schedule a single operation in a
    /// non-default context, or temporarily use a non-default context in
    /// the main thread. In that case, you can wrap the call to the
    /// asynchronous operation inside a
    /// [`with_thread_default()`][Self::with_thread_default()] /
    /// [`pop_thread_default()`][Self::pop_thread_default()] pair, but it is up to you to
    /// ensure that no other asynchronous operations accidentally get
    /// started while the non-default context is active.
    ///
    /// Beware that libraries that predate this function may not correctly
    /// handle being used from a thread with a thread-default context. For example,
    /// see `g_file_supports_thread_contexts()`.
    // rustdoc-stripper-ignore-next-stop
    /// Acquires @self and sets it as the thread-default context for the
    /// current thread. This will cause certain asynchronous operations
    /// (such as most [Gio](../gio/index.html)-based I/O) which are
    /// started in this thread to run under @self and deliver their
    /// results to its main loop, rather than running under the global
    /// default main context in the main thread. Note that calling this function
    /// changes the context returned by [`thread_default()`][Self::thread_default()],
    /// not the one returned by [`default()`][Self::default()], so it does not
    /// affect the context used by functions like `idle_add()`.
    ///
    /// Normally you would call this function shortly after creating a new
    /// thread, passing it a [`MainContext`][crate::MainContext] which will be run by a
    /// [`MainLoop`][crate::MainLoop] in that thread, to set a new default context for all
    /// async operations in that thread. In this case you may not need to
    /// ever call [`pop_thread_default()`][Self::pop_thread_default()], assuming you want
    /// the new [`MainContext`][crate::MainContext] to be the default for the whole lifecycle
    /// of the thread.
    ///
    /// If you don’t have control over how the new thread was created (e.g.
    /// in the new thread isn’t newly created, or if the thread life
    /// cycle is managed by a #GThreadPool), it is always suggested to wrap
    /// the logic that needs to use the new [`MainContext`][crate::MainContext] inside a
    /// [`with_thread_default()`][Self::with_thread_default()] /
    /// [`pop_thread_default()`][Self::pop_thread_default()] pair, otherwise threads that
    /// are re-used will end up never explicitly releasing the
    /// [`MainContext`][crate::MainContext] reference they hold.
    ///
    /// In some cases you may want to schedule a single operation in a
    /// non-default context, or temporarily use a non-default context in
    /// the main thread. In that case, you can wrap the call to the
    /// asynchronous operation inside a
    /// [`with_thread_default()`][Self::with_thread_default()] /
    /// [`pop_thread_default()`][Self::pop_thread_default()] pair, but it is up to you to
    /// ensure that no other asynchronous operations accidentally get
    /// started while the non-default context is active.
    ///
    /// Beware that libraries that predate this function may not correctly
    /// handle being used from a thread with a thread-default context. For example,
    /// see `g_file_supports_thread_contexts()`.
    #[doc(alias = "g_main_context_push_thread_default")]
    pub fn with_thread_default<R, F: FnOnce() -> R + Sized>(
        &self,
        func: F,
    ) -> Result<R, crate::BoolError> {
        let _acquire = self.acquire()?;
        let _thread_default = ThreadDefaultContext::new(self);
        Ok(func())
    }

    // rustdoc-stripper-ignore-next
    /// Acquire ownership of the main context.
    ///
    /// Ownership will automatically be released again once the returned acquire guard is dropped.
    ///
    /// This will fail if the main context is owned already by another thread.
    // rustdoc-stripper-ignore-next-stop
    /// Tries to become the owner of the specified context.
    ///
    /// If some other thread is the owner of the context,
    /// returns false immediately. Ownership is properly
    /// recursive: the owner can require ownership again
    /// and will release ownership when [`release()`][Self::release()]
    /// is called as many times as [`acquire()`][Self::acquire()].
    ///
    /// You must be the owner of a context before you
    /// can call [`prepare()`][Self::prepare()], `GLib::MainContext::query()`,
    /// `GLib::MainContext::check()`, [`dispatch()`][Self::dispatch()],
    /// [`release()`][Self::release()].
    ///
    /// Since 2.76 @self can be `NULL` to use the global-default
    /// main context.
    ///
    /// # Returns
    ///
    /// true if this thread is now the owner of @self, false otherwise
    // rustdoc-stripper-ignore-next-stop
    /// Tries to become the owner of the specified context.
    ///
    /// If some other thread is the owner of the context,
    /// returns false immediately. Ownership is properly
    /// recursive: the owner can require ownership again
    /// and will release ownership when [`release()`][Self::release()]
    /// is called as many times as [`acquire()`][Self::acquire()].
    ///
    /// You must be the owner of a context before you
    /// can call [`prepare()`][Self::prepare()], `GLib::MainContext::query()`,
    /// `GLib::MainContext::check()`, [`dispatch()`][Self::dispatch()],
    /// [`release()`][Self::release()].
    ///
    /// Since 2.76 @self can be `NULL` to use the global-default
    /// main context.
    ///
    /// # Returns
    ///
    /// true if this thread is now the owner of @self, false otherwise
    #[doc(alias = "g_main_context_acquire")]
    pub fn acquire(&self) -> Result<MainContextAcquireGuard<'_>, crate::BoolError> {
        unsafe {
            let ret: bool = from_glib(ffi::g_main_context_acquire(self.to_glib_none().0));
            if ret {
                Ok(MainContextAcquireGuard(self))
            } else {
                Err(bool_error!(
                    "Failed to acquire ownership of main context, already acquired by another thread"
                ))
            }
        }
    }
}

#[must_use = "if unused the main context will be released immediately"]
pub struct MainContextAcquireGuard<'a>(&'a MainContext);

impl Drop for MainContextAcquireGuard<'_> {
    #[doc(alias = "g_main_context_release")]
    #[inline]
    fn drop(&mut self) {
        unsafe {
            ffi::g_main_context_release(self.0.to_glib_none().0);
        }
    }
}

struct ThreadDefaultContext<'a>(&'a MainContext);

impl ThreadDefaultContext<'_> {
    fn new(ctx: &MainContext) -> ThreadDefaultContext<'_> {
        unsafe {
            ffi::g_main_context_push_thread_default(ctx.to_glib_none().0);
        }
        ThreadDefaultContext(ctx)
    }
}

impl Drop for ThreadDefaultContext<'_> {
    #[inline]
    fn drop(&mut self) {
        unsafe {
            ffi::g_main_context_pop_thread_default(self.0.to_glib_none().0);
        }
    }
}

#[cfg(test)]
mod tests {
    use std::{panic, ptr, thread};

    use super::*;

    #[test]
    fn test_invoke() {
        let c = MainContext::new();
        let l = crate::MainLoop::new(Some(&c), false);

        let l_clone = l.clone();
        let join_handle = thread::spawn(move || {
            c.invoke(move || l_clone.quit());
        });

        l.run();

        join_handle.join().unwrap();
    }

    fn is_same_context(a: &MainContext, b: &MainContext) -> bool {
        ptr::eq(a.to_glib_none().0, b.to_glib_none().0)
    }

    #[test]
    fn test_with_thread_default() {
        let a = MainContext::new();
        let b = MainContext::new();

        assert!(!is_same_context(&a, &b));

        a.with_thread_default(|| {
            let t = MainContext::thread_default().unwrap();
            assert!(is_same_context(&a, &t));

            b.with_thread_default(|| {
                let t = MainContext::thread_default().unwrap();
                assert!(is_same_context(&b, &t));
            })
            .unwrap();

            let t = MainContext::thread_default().unwrap();
            assert!(is_same_context(&a, &t));
        })
        .unwrap();
    }

    #[test]
    fn test_with_thread_default_is_panic_safe() {
        let a = MainContext::new();
        let b = MainContext::new();

        assert!(!is_same_context(&a, &b));

        a.with_thread_default(|| {
            let t = MainContext::thread_default().unwrap();
            assert!(is_same_context(&a, &t));

            let result = panic::catch_unwind(|| {
                b.with_thread_default(|| {
                    panic!();
                })
                .unwrap();
            });
            assert!(result.is_err());

            let t = MainContext::thread_default().unwrap();
            assert!(is_same_context(&a, &t));
        })
        .unwrap();
    }
}