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::*, MainContext};

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. (@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).
    ///
    /// @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 #GSource 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() }
    //}

    #[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 the [`MainContext`][crate::MainContext] with which the source is associated.
    ///
    /// You can call this on a source that has been destroyed, provided
    /// that the [`MainContext`][crate::MainContext] it was attached to still exists (in which
    /// case it will return that [`MainContext`][crate::MainContext]). In particular, you can
    /// always call this function on the source returned from
    /// [`main_current_source()`][crate::main_current_source()]. But calling this function on a source
    /// whose [`MainContext`][crate::MainContext] has been destroyed is an error.
    ///
    /// # Returns
    ///
    /// the #GMainContext with which the
    ///               source is associated, or [`None`] if the context has not
    ///               yet been added to a source.
    #[doc(alias = "g_source_get_context")]
    #[doc(alias = "get_context")]
    pub fn context(&self) -> Option<MainContext> {
        unsafe { from_glib_none(ffi::g_source_get_context(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 0)
    /// 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 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) }
    }

    /// 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 #GSource 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
    #[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 #GSource.
    /// Do not call this API on a #GSource that you did not create.
    /// ## `child_source`
    /// a #GSource 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 {}