glib/auto/

source.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

use crate::{ffi, translate::*};

crate::wrapper! {
    /// The `GSource` struct is an opaque data type
    /// representing an event source.
    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct Source(Shared<ffi::GSource>);

    match fn {
        ref => |ptr| ffi::g_source_ref(ptr),
        unref => |ptr| ffi::g_source_unref(ptr),
        type_ => || ffi::g_source_get_type(),
    }
}

impl Source {
    //#[doc(alias = "g_source_new")]
    //pub fn new(source_funcs: /*Ignored*/&mut SourceFuncs, struct_size: u32) -> Source {
    //    unsafe { TODO: call ffi:g_source_new() }
    //}

    /// Adds @child_source to @self as a ‘polled’ source.
    ///
    /// When @self is added to a [`MainContext`][crate::MainContext], @child_source will be
    /// automatically added with the same priority. When @child_source is triggered,
    /// it will cause @self to dispatch (in addition to calling its own callback),
    /// and when @self is destroyed, it will destroy @child_source as well.
    ///
    /// The @self will also still be dispatched if its own prepare/check functions
    /// indicate that it is ready.
    ///
    /// If you don’t need @child_source to do anything on its own when it
    /// triggers, you can call `g_source_set_dummy_callback()` on it to set a
    /// callback that does nothing (except return true if appropriate).
    ///
    /// The @self will hold a reference on @child_source while @child_source
    /// is attached to it.
    ///
    /// This API is only intended to be used by implementations of [`Source`][crate::Source].
    /// Do not call this API on a [`Source`][crate::Source] that you did not create.
    /// ## `child_source`
    /// a second source that @self should ‘poll’
    #[doc(alias = "g_source_add_child_source")]
    pub fn add_child_source(&self, child_source: &Source) {
        unsafe {
            ffi::g_source_add_child_source(self.to_glib_none().0, child_source.to_glib_none().0);
        }
    }

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

    //#[doc(alias = "g_source_add_unix_fd")]
    //pub fn add_unix_fd(&self, fd: i32, events: IOCondition) -> /*Unimplemented*/Basic: Pointer {
    //    unsafe { TODO: call ffi:g_source_add_unix_fd() }
    //}

    /// Unsets any previously set ready time.
    ///
    /// If the source does not have a ready time set, this function
    /// does nothing.
    #[cfg(feature = "v2_90")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_90")))]
    #[doc(alias = "g_source_clear_ready_time")]
    pub fn clear_ready_time(&self) {
        unsafe {
            ffi::g_source_clear_ready_time(self.to_glib_none().0);
        }
    }

    #[doc(alias = "g_source_destroy")]
    pub fn destroy(&self) {
        unsafe {
            ffi::g_source_destroy(self.to_glib_none().0);
        }
    }

    /// Checks whether a source is allowed to be called recursively.
    ///
    /// See `GLib::Source::set_can_recurse()`.
    ///
    /// # Returns
    ///
    /// whether recursion is allowed
    #[doc(alias = "g_source_get_can_recurse")]
    #[doc(alias = "get_can_recurse")]
    pub fn can_recurse(&self) -> bool {
        unsafe { from_glib(ffi::g_source_get_can_recurse(self.to_glib_none().0)) }
    }

    /// Gets a name for the source, used in debugging and profiling.
    ///
    /// The
    /// name may be `NULL` if it has never been set with `GLib::Source::set_name()`.
    ///
    /// # Returns
    ///
    /// the name of the source
    #[doc(alias = "g_source_get_name")]
    #[doc(alias = "get_name")]
    pub fn name(&self) -> Option<crate::GString> {
        unsafe { from_glib_none(ffi::g_source_get_name(self.to_glib_none().0)) }
    }

    /// Gets the priority of a source.
    ///
    /// # Returns
    ///
    /// the priority of the source
    #[doc(alias = "g_source_get_priority")]
    #[doc(alias = "get_priority")]
    pub fn priority(&self) -> i32 {
        unsafe { ffi::g_source_get_priority(self.to_glib_none().0) }
    }

    /// Gets the ‘ready time’ of @self, as set by
    /// `GLib::Source::set_ready_time()`.
    ///
    /// Any time before or equal to the current monotonic time (including zero)
    /// is an indication that the source will fire immediately.
    ///
    /// # Returns
    ///
    /// the monotonic ready time, `-1` for ‘never’
    #[doc(alias = "g_source_get_ready_time")]
    #[doc(alias = "get_ready_time")]
    pub fn ready_time(&self) -> i64 {
        unsafe { ffi::g_source_get_ready_time(self.to_glib_none().0) }
    }

    /// Gets the ‘ready time’ of @self, as set by
    /// `GLib::Source::set_ready_time_ns()`. If no ready time has been set
    /// or it has been cleared via method@GLib.Source.clear_ready_time], this
    /// function returns false.
    ///
    /// Any time before or equal to the current monotonic time (including zero)
    /// is an indication that the source will fire immediately.
    ///
    /// # Returns
    ///
    /// true if the source has a ready time set.
    ///
    /// ## `ready_time`
    /// Set to the ready time
    ///   on success
    #[cfg(feature = "v2_90")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_90")))]
    #[doc(alias = "g_source_get_ready_time_ns")]
    #[doc(alias = "get_ready_time_ns")]
    pub fn ready_time_ns(&self) -> Option<u64> {
        unsafe {
            let mut ready_time = std::mem::MaybeUninit::uninit();
            let ret = from_glib(ffi::g_source_get_ready_time_ns(
                self.to_glib_none().0,
                ready_time.as_mut_ptr(),
            ));
            if ret {
                Some(ready_time.assume_init())
            } else {
                None
            }
        }
    }

    /// Gets the time to be used when checking this source.
    ///
    /// The advantage of
    /// calling this function over calling [`monotonic_time()`][crate::monotonic_time()] directly is
    /// that when checking multiple sources, GLib can cache a single value
    /// instead of having to repeatedly get the system monotonic time.
    ///
    /// The time here is the system monotonic time, if available, or some
    /// other reasonable alternative otherwise.  See [`monotonic_time()`][crate::monotonic_time()].
    ///
    /// # Returns
    ///
    /// the monotonic time in microseconds
    #[doc(alias = "g_source_get_time")]
    #[doc(alias = "get_time")]
    pub fn time(&self) -> i64 {
        unsafe { ffi::g_source_get_time(self.to_glib_none().0) }
    }

    /// Gets the time to be used when checking this source.
    ///
    /// The advantage of calling this function over calling
    /// [`monotonic_time_ns()`][crate::monotonic_time_ns()] directly is
    /// that when checking multiple sources, GLib can cache a single value
    /// instead of having to repeatedly get the system monotonic time.
    ///
    /// The time here is the system monotonic time, if available, or some
    /// other reasonable alternative otherwise.  See [`monotonic_time_ns()`][crate::monotonic_time_ns()].
    ///
    /// # Returns
    ///
    /// the monotonic time in nanoseconds
    #[cfg(feature = "v2_90")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_90")))]
    #[doc(alias = "g_source_get_time_ns")]
    #[doc(alias = "get_time_ns")]
    pub fn time_ns(&self) -> u64 {
        unsafe { ffi::g_source_get_time_ns(self.to_glib_none().0) }
    }

    /// Returns whether @self has been destroyed.
    ///
    /// This is important when you operate upon your objects
    /// from within idle handlers, but may have freed the object
    /// before the dispatch of your idle handler.
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// static gboolean
    /// idle_callback (gpointer data)
    /// {
    ///   SomeWidget *self = data;
    ///
    ///   g_mutex_lock (&self->idle_id_mutex);
    ///   // do stuff with self
    ///   self->idle_id = 0;
    ///   g_mutex_unlock (&self->idle_id_mutex);
    ///
    ///   return G_SOURCE_REMOVE;
    /// }
    ///
    /// static void
    /// some_widget_do_stuff_later (SomeWidget *self)
    /// {
    ///   g_mutex_lock (&self->idle_id_mutex);
    ///   self->idle_id = g_idle_add (idle_callback, self);
    ///   g_mutex_unlock (&self->idle_id_mutex);
    /// }
    ///
    /// static void
    /// some_widget_init (SomeWidget *self)
    /// {
    ///   g_mutex_init (&self->idle_id_mutex);
    ///
    ///   // ...
    /// }
    ///
    /// static void
    /// some_widget_finalize (GObject *object)
    /// {
    ///   SomeWidget *self = SOME_WIDGET (object);
    ///
    ///   if (self->idle_id)
    ///     g_source_remove (self->idle_id);
    ///
    ///   g_mutex_clear (&self->idle_id_mutex);
    ///
    ///   G_OBJECT_CLASS (parent_class)->finalize (object);
    /// }
    /// ```
    ///
    /// This will fail in a multi-threaded application if the
    /// widget is destroyed before the idle handler fires due
    /// to the use after free in the callback. A solution, to
    /// this particular problem, is to check to if the source
    /// has already been destroy within the callback.
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// static gboolean
    /// idle_callback (gpointer data)
    /// {
    ///   SomeWidget *self = data;
    ///
    ///   g_mutex_lock (&self->idle_id_mutex);
    ///   if (!g_source_is_destroyed (g_main_current_source ()))
    ///     {
    ///       // do stuff with self
    ///     }
    ///   g_mutex_unlock (&self->idle_id_mutex);
    ///
    ///   return FALSE;
    /// }
    /// ```
    ///
    /// Calls to this function from a thread other than the one acquired by the
    /// [`MainContext`][crate::MainContext] the [`Source`][crate::Source] is attached to are typically
    /// redundant, as the source could be destroyed immediately after this function
    /// returns. However, once a source is destroyed it cannot be un-destroyed, so
    /// this function can be used for opportunistic checks from any thread.
    ///
    /// # Returns
    ///
    /// true if the source has been destroyed, false otherwise
    #[doc(alias = "g_source_is_destroyed")]
    pub fn is_destroyed(&self) -> bool {
        unsafe { from_glib(ffi::g_source_is_destroyed(self.to_glib_none().0)) }
    }

    //#[doc(alias = "g_source_modify_unix_fd")]
    //pub fn modify_unix_fd(&self, tag: /*Unimplemented*/Basic: Pointer, new_events: IOCondition) {
    //    unsafe { TODO: call ffi:g_source_modify_unix_fd() }
    //}

    //#[doc(alias = "g_source_query_unix_fd")]
    //pub fn query_unix_fd(&self, tag: /*Unimplemented*/Basic: Pointer) -> IOCondition {
    //    unsafe { TODO: call ffi:g_source_query_unix_fd() }
    //}

    /// Detaches @child_source from @self and destroys it.
    ///
    /// This API is only intended to be used by implementations of [`Source`][crate::Source].
    /// Do not call this API on a [`Source`][crate::Source] that you did not create.
    /// ## `child_source`
    /// a source previously passed to
    ///   [`add_child_source()`][Self::add_child_source()]
    #[doc(alias = "g_source_remove_child_source")]
    pub fn remove_child_source(&self, child_source: &Source) {
        unsafe {
            ffi::g_source_remove_child_source(self.to_glib_none().0, child_source.to_glib_none().0);
        }
    }

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

    //#[doc(alias = "g_source_remove_unix_fd")]
    //pub fn remove_unix_fd(&self, tag: /*Unimplemented*/Basic: Pointer) {
    //    unsafe { TODO: call ffi:g_source_remove_unix_fd() }
    //}

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

    //#[doc(alias = "g_source_remove_by_user_data")]
    //pub fn remove_by_user_data(user_data: /*Unimplemented*/Option<Basic: Pointer>) -> bool {
    //    unsafe { TODO: call ffi:g_source_remove_by_user_data() }
    //}
}

unsafe impl Send for Source {}
unsafe impl Sync for Source {}