Struct glib::Source

source ·

pub struct Source { /* private fields */ }

Expand description

The GSource struct is an opaque data type representing an event source.

Implementations§

source §

impl Source

source

pub fn as_ptr(&self) -> *mut GSource

Return the inner pointer to the underlying C value.

source

pub unsafe fn from_glib_ptr_borrow<'a>(ptr: const const GSource) -> &'a Self

Borrows the underlying C value.

source §

Adds @child_source to @self as a “polled” source; when @self is added to a #GMainContext, @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 #GSource. Do not call this API on a #GSource that you did not create.

§`child_source`

a second #GSource that @self should “poll”

source

pub fn destroy(&self)

source

pub fn can_recurse(&self) -> bool

Checks whether a source is allowed to be called recursively. see g_source_set_can_recurse().

§Returns

whether recursion is allowed.

source

pub fn context(&self) -> Option<MainContext>

Gets the #GMainContext with which the source is associated.

You can call this on a source that has been destroyed, provided that the #GMainContext it was attached to still exists (in which case it will return that #GMainContext). In particular, you can always call this function on the source returned from g_main_current_source(). But calling this function on a source whose #GMainContext 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.

source

pub fn name(&self) -> Option<GString>

Gets a name for the source, used in debugging and profiling. The name may be #NULL if it has never been set with g_source_set_name().

§Returns

the name of the source

source

pub fn priority(&self) -> i32

Gets the priority of a source.

§Returns

the priority of the source

source

pub fn ready_time(&self) -> i64

Gets the “ready time” of @self, as set by g_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”

source

pub fn time(&self) -> i64

Gets the time to be used when checking this source. The advantage of calling this function over calling g_get_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 g_get_monotonic_time().

§Returns

the monotonic time in microseconds

source

pub fn is_destroyed(&self) -> bool

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 ⚠️

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 ⚠️

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 #GMainContext 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.